Cognos 8 Planning

ANALYST USER GUIDE

Product Information
This document applies to Cognos 8 Planning Version 8.3 and may also apply to subsequent releases. To check for newer versions of this document, visit the Cognos Global Customer Services Web site (http://support.cognos.com).

Copyright
Copyright 2007 Cognos Incorporated. Portions of Cognos software products are protected by one or more of the following U.S. Patents: 6,609,123 B1; 6,611,838 B1; 6,662,188 B1; 6,728,697 B2; 6,741,982 B2; 6,763,520 B1; 6,768,995 B2; 6,782,378 B2; 6,847,973 B2; 6,907,428 B2; 6,853,375 B2; 6,986,135 B2; 6,995,768 B2; 7,062,479 B2; 7,072,822 B2; 7,111,007 B2; 7,130,822 B1; 7,155,398 B2; 7,171,425 B2; 7,185,016 B1;7,213,199 B2. Cognos and the Cognos logo are trademarks of Cognos Incorporated in the United States and/or other countries. All other names are trademarks or registered trademarks of their respective companies. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to either the product or the document will be documented in subsequent editions. U.S. Government Restricted Rights. The software and accompanying materials are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to the restrictions in subparagraph (C)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013, or subparagraphs (C)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48CFR52.227-19, as applicable. The Contractor is Cognos Corporation, 15 Wayside Road, Burlington, MA 01803. This software/documentation contains proprietary information of Cognos Incorporated. All rights are reserved. Reverse engineering of this software is prohibited. No part of this software/documentation may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos Incorporated.

Table of Contents
Introduction

19

What's New? 23 New Features in Version 8.3 23 Microsoft Excel 2007 23 Select Folders in Cognos Connection 23 Select Framework Manager Package for D-List Import 23 Chapter 1: Analyst Overview

25

Saving Analyst Data 25 Registry Settings 25 Restart Analyst 26 Understanding Analyst 26 Formulas in Analyst and Excel Spreadsheets 26 Using LIB and LIBNO Parameters 27 Other Differences 27 Multi-User Object Access 28 Analyst Samples 28 Tutorialgo 29 Great Outdoors Analyst 29 The BiF Library 31 The Slice Update Sample 31 Customizing the Analyst Toolbar 34 Use Custom Menus 35 Create Custom Toolbar Buttons 36 Chapter 2: Administration

37

Viewing and Editing Analyst Workspace Settings 37 Creating Planning Tables 38 Set Filesys.ini 38 Rebuild Index Files 39 Refresh References 39 Validate D-Lists 39 DOS File Names 39 Close ODBC Links 40 Configuration Settings 40 Chapter 3: Objects

43

Add a Description to an Object 43 Reveal Object Name from DOS Filename 43 Chapter 4: Security

45

Cognos Namespace 45 Authentication Providers 46 Deleting or Restoring Unconfigured Namespaces 47

User Guide 3

Table of Contents Users, Groups, and Roles 47 Users 48 Groups and Roles 48 Setting up Security for a Cognos 8 Planning Installation 50 Configure Cognos 8 to Use an Authentication Provider 51 Add or Remove Members From Planning Rights Administrators and Planning Contributor Users Roles 52 Enabling Planning Roles in Cognos 8 53 Restricting Access to the Everyone Group 53 Recommendation - Creating Additional Roles or Groups for Contributor 54 Configuring Access to Analyst 54 Configure Integrated Windows Authentication 56 Specify a Default Library 57 Restrict D-Cube Access 57 Assign Access at the Library Level 57 Assigning Access at the Object Level 58 Assigning Access at the Item Level 60 Chapter 5: Integration

63

Financial Planning with Cognos Finance and Cognos Planning Products 63 Prerequisites and Required Components 64 Understanding the Process 64 Using Cognos Finance Input Forms or Report Files 65 Importing From Cognos Finance 65 Financial Planning with Cognos Performance Applications and Analyst 67 IQD Files and the Import from IQD Wizard 68 Creating Planning Models and Data from Cognos Performance Applications Data 72 Determine Plan Granularity 74 Create a Planning Model in Analyst 74 Set up a Contributor Application 76 Populate the Planning Application in Contributor 77 Publish Planning Data 79 Automation 81 Command Line 81 Chapter 6: Importing Data from Cognos 8 Data Sources

83

Create a Data Source Connection 84 Create a Framework Manager Project and Import Metadata 86 Create and Publish the Cognos Package 87 Working with SAP BW Data 88 Create a Detailed Fact Query Subject 88 Recommendation - Query Items 89 Recommendation - Hierarchy 89 Recommendation - Hiding the Dimension Key Field 90 Working with Packages 90 Chapter 7: D-Lists

91

Open a D-List 91 Create a D-List 91 Formulas 93

4 Analyst

Table of Contents Import a Formula (CalcTexts) 93 Preview or Print the Formulas 95 Create a Subtotal 95 Enter a Formula into a D-List 95 Edit a Formula 97 Copy a Formula 97 Remove a Formula 98 Troubleshooting Formula Errors 98 View Formulas 100 D-List Conditional Formulas 101 Formula Priority 104 Apply a Time Average 106 Weighted Averages 106 Choosing Which Item to Weight By 107 Apply a Weighted Average 107 Override a Weighted Average 108 Force to Zero 108 Remove Averages 108 Applying Local Formats to D-Lists 109 Types of Formats 109 Assign Local Formats 110 Save a Local Format 110 Load a Local Format 110 Formulas and D-List Formatted Items 111 Format a Specific Row or Column 111 Numeric Formats 112 Date and Time Formats 114 Apply D-List Formats 117 Apply Free-Text Format to a D-List Item 118 Timescale D-Lists 118 Create a Timescale D-List 119 Create a Custom Timescale 120 Timescales and BiFs 120 Common Errors in Timescales 120 Set Periods of Uneven Lengths 120 Copy an Existing D-List 121 Edit a D-List 121 Edit D-List Item Names 123 Insert items from a D-List 123 Create an Import Link into a D-List 124 Run an Import Link into a D-List 124 Paste Items from a Spreadsheet, Database, or Other Text Source 125 Import D-List Items from Another D-List 125 Import D-List Items from Unmapped ASCII Files 126 Import D-List Data from Mapped ASCII Files 127 Import D-List Items from a D-Cube 128 Import D-List Items Using ODBC 129 Import D-List Items From a Cognos Package 130 Export a D-List as an e-List 131

User Guide 5

Table of Contents Implement Changes 131 Delete items from a D-List 131 Import Mode 132 Example - Import Modes 132 Copying from Another D-List 133 Importing from ASCII files, ODBC sources, Cognos Packages, or D-Cube data 134 Where Drop-Box 135 Subtotals Drop-Box 135 Maintaining Hierarchies 135 Manage D-Lists 139 Rename/Move a D-List 139 << Move 139 Delete a D-List 139 Search for a D-List 140 Show a D-List's Dependants 140 Show a D-List's Precedents 140 Upgrade Pipe Symbols in D-List Item Names 141 Unique Names 141 Edit Unique Names 141 Define the Unique Part of a D-List Item 141 Manually Reorder D-List Items 142 Sort D-List Items 143 View/Edit Summary Information on a D-List 144 Add Sub Headings to Reports 145 Set D-List Colors 146 Chapter 8: D-Cubes

147

Interrupt a Calculation 148 Set or Clear Audit Trails 148 View the Audit Trail of a Cell Within a D-Cube 149 Breakback 149 Default Rules for Breakback 149 Use Breakback to Set Global Targets 151 Holds and Breakback 151 Using Breakback with Integer Arithmetic 152 Set Breakback to Integer or Decimal Mode 153 Set a Target Using Breakback 153 Create D-Cubes 154 Open D-Cubes 156 Open Multiple D-Cubes 157 Expand a Subtotal 157 View Multiple Slices of a D-Cube in Separate Windows 157 D-Cube Data Allocations 158 Enter Data 159 Enter Data into Individual Cells of a D-Cube 159 Color Conventions for Data 160 View a Formula 161 View the Origin of a Detail Cell 161 Edit D-Cubes 161

6 Analyst

Table of Contents Copy a Range on the Same Page 161 Copy Ranges in a D-Cube from Page to Page 162 Copy Data Using Operators 163 Copy from a Spreadsheet to Analyst 163 Insert Lines to Separate Totals from Detail Items 164 Edit Undo and Redo 165 Suppress Zero Rows, Columns, or Pages 165 Reveal All Zero Suppressed Rows and Columns 166 Change the Column Width or Row Label Width 166 Annotate a Cell 167 Edit Data 168 Edit Data on the Current Page of a D-Cube 168 Edit the Data in Individual Cells Using Operators 169 Select a Range of Cells in a D-Cube 170 Reset Data 171 Recover from Errors 172 D-Cube Commands 173 Apply Commands 175 Edit a Range of Data on the Current Page 176 Delete the Data from an Entire D-Cube 176 Set a Column or Row to Zero 177 Change Ranges of Data Using Menu Commands 178 Locks, Protects, and Holds 180 Hold Data 181 Protect Data 183 Lock Data 183 Special Copy and Paste 185 Random Number D-Cube Command 185 Round Command 185 Export Data 186 D-Cube Export 186 Format Prior to Export 189 Export to a Spreadsheet 190 AutoSum 190 Find Text and Character Matches 191 Formats 191 Local vs Global Formats 191 Load or Remove a Global Format 191 Save a Global Format 192 Enter Prefixes and Suffixes 192 Access Blank if Zero 193 D-Cube Selections 193 Expanded Selections 193 Creating a Selection 194 Facilitate Selection Using the Selection Dialog Box 195 Saved Selections and D-Links 197 Save a Selection 197 Load a Saved Selection 198 Load a Saved Selection on Opening a D-Cube 198

User Guide 7

Table of Contents Edit the Selection on Opening a D-Cube 199 Edit a Saved Selection 200 Manage D-Cubes 202 Memory Management 202 Split Column Headings onto Two Lines 203 Show Details or Formulas Only 203 Sort Rows, Columns, and Pages 204 Manipulate D-Cube Structure 205 Work with Dimensions 207 Navigate Around a D-Cube 212 View a Different Slice 212 View a Different Page 213 Save D-Cubes 213 Chapter 9: D-Links

215

The D-Link Dialog Box 216 Dimensions and D-Lists 216 Create D-Links 217 Use D-Cube as Source and Target 217 Use Cognos Package as Source in a D-Link 218 Pair Source and Target Dimensions 219 Select Required Items from Unpaired Dimensions 219 Change Optional Settings in D-Link 220 Name and Save the D-Link 220 Open D-Links 220 Open More than One D-Link 221 Open a D-Link that Targets an Open D-Cube 221 Open a D-Link that Uses an Open D-Cube as its Source 221 Open D-Links Associated with Selected D-Cubes 222 Run D-Links 222 Run an Open D-Link 223 Run a D-Link Using a Specific D-Cube as its Source or Target 223 Run a D-Link Using an Open D-Cube as its Target 223 Run D-Links with the Source D-Cube Open 224 Run Update D-Links in a Single D-Cube (Manually) 225 Run Batches of D-Links Using Library Functions 225 Memory Considerations 226 Run Batches of D-Links using Macros 227 Tun an Inverse D-Link 227 Dimensions 230 Virtual Dimensions 230 Dimensions and D-Lists 230 Unvisited Dimensions 230 Unpaired Dimensions 231 Match Descriptions 233 How Match Descriptions Pairs Data 233 Create a Match Descriptions Pairing 233 Case Sensitivity 234 Match Calculated Target Items 235

8 Analyst

Table of Contents Allocation 235 Maintain Allocation Tables 236 Allocation Table Menu Options 236 How Allocation Tables Assign Data 237 Navigate Around an Allocation Table 238 Load an A-Table into a D-Link 240 Change to Matched Descriptions 240 Change to Allocation 241 Change Dimension Items in a D-Link 241 Target Formula Items 241 Local Allocation Tables (A-Tables) 242 Create a Local Allocation Table Pairing 242 Delete Entries in a Local Allocation Table 244 Use Wildcard Characters in Local Allocation Tables 244 Edit Local Allocation Table Entries 246 Reorder Lines in a Local Allocation Table 246 Add Entries to a Local A-Table 246 Loaded Allocation Tables 248 Saved Allocation Tables 248 Copy and Paste Allocation Table Entries 248 D-Cube Allocations 249 Example 249 Use D-Cube Data in Allocation 250 Select and Slice an Allocation D-Cube 250 Execution Modes 252 Run D-Links inversely 252 Fill Mode 253 Substitute Mode 253 Add Mode 253 Subtract Mode 253 The Target Area 253 Dump Options 254 When will records be unassigned? 255 Edit 255 Print 255 File 255 Dump Item 256 Drill Down on Data Assigned to Dump Items 257 Dump Items Used with Dump Options 257 Scale and Round Data within a D-Link 257 Scaling Factors 257 Rounding Factors 257 Set Scaling and Rounding 258 Subcolumns 259 Cut a Subcolumn 259 Change the Position of an Existing Subcolumn 260 Clear a Subcolumn 261 Duplicate Target Items 261 Lookup and Accumulation D-Links 262

User Guide 9

Table of Contents Database D-Cube 262 Sparse D-Cube 262 Lookup and Accumulation D-Link Restrictions 264 Lookup D-Links 264 Accumulation D-Links 270 Analyst<>Contributor Links 276 When to use Analyst<>Contributor Links 276 Installation 277 Security 277 How Analyst<>Contributor and Contributor<>Contributor Links Work 278 Copying Analyst<>Contributor Links 280 Library Method 280 Library Copy Wizard Method 281 Factors That Can Affect Memory Usage 281 Opening a Link From a Computer that Does not Have Access to the Original Datastore 282 Running Batches of D-Links using the @DLinkExecuteList macro 282 Running D-Links While Making Model Changes 283 Effect of Access Tables in Contributor 284 Select Contributor Application 284 Analyst<>Cognos Finance Links 285 When to Use Analyst <> Cognos Finance Links 286 Installation 286 How Analyst <> Cognos Finance Links Work 286 D-Link Options 286 One-off and Internal D-Links 286 Fill a D-Cube with Data Using a One-Off Internal D-Link 287 Date Allocations 287 Copy data in a D-Cube from Page to Page 288 Update Models Using D-Cube Update List 288 Order of Running D-Links 289 D-Cube Update List Dialog Box 289 Drill Down 290 How Drill Down Works 291 Drill Down on a Cell Using a Source or Mapped ASCII File 291 Drill Down on One Cell Using a D-Cube as a Source 291 Drill Down on a Range of Cells 292 Drill Down on Break Back Allocations 293 Troubleshoot D-Links 294 The "Nothing to Transfer" Message 294 Nothing Happens When You Drill Down 294 Error Messages Appear When You Drill Down 295 Chapter 10: ODBC Links

297

Creating ODBC Links 297 Install an ODBC Driver 297 Set Up an ODBC Data Source 298 Import Using ODBC 298 Import D-List Items into a D-List Using ODBC 298 Import Data into a D-Cube Using an ODBC Link 299

10 Analyst

Table of Contents Chapter 11: Libraries

301

Work with Libraries 301 Library Administration 302 Create a Library 302 Delete a Library 303 Display Library Name 303 Change Library Details 303 The Library Window 304 Rename an Object 304 Delete an Object 304 Move an Object to a Different Library 305 Show the Precedents of an Object 305 Show the Dependants of an Object 306 Highlight Unused Objects in the Library 307 Reveal the DOS File Name 307 Show the Description of an Object 307 Copy Objects 307 Remap Objects 308 Check Integrity 309 Open Multiple Objects 310 Copy Libraries or Objects Using the Library Copy Wizard 310 Select Libraries 311 Select Objects 312 Chapter 12: Built in Functions (BiFs) BiF Library 315 Work with BiFs 316 Steps to Create a BiF 316 Steps to Edit a BiF 316 Steps to Delete a BiF 317 BiF Results 317 BiF Outputs 317 Priority of Calculations 319 Circularity in BiFs 319 Nesting in BiFs 319 Breakback in BiFs 320 BiF Input Parameters 320 Show Calculation Errors 320 BiF Examples 320 Overview of Examples 320 @Cumul 324 @Cycles 324 @Days 327 @DaysOutstanding 328 @DCF 331 @Decum 336 @Delay 337 @DelayDebt 340 @DelayStock 343

315

User Guide 11

Table of Contents @DepnAnnual 346 @DepnDB 352 @DepnSLN 355 @DepnSYD 356 @Deytd 359 @Differ 360 @Drive 362 @Drive1 365 @Drive2 368 @ErlangDelayAgents 371 @ErlangDelayFull 373 @ErlangDelayLite 375 @ErlangLossLite 375 Understanding the Erlang BiFs Equations 376 Erlang Built-in Functions Glossary 378 @Feed 379 @FeedParam 380 @Forecast 383 @Funds 394 @FV 395 @Grow 406 @ICF 408 @IRR 411 @Lag 418 @Last 421 @Lease 423 @LeaseVariable 443 @Linavg 472 @Mix 473 @Movavg & @Movsum 475 MoveMed 481 @Nper 484 @NPV 493 @Outlook 498 @PMT 501 @PV 509 @Proportion 517 @Rate 518 @Repeat 529 @SeasonLite 529 @SeasonPro 533 @Simul 568 @StockFlow 571 @StockFlowAF 577 @StockflowBQ 582 @Tier 585 @Time 586 @TimeSum 593 @TMax 601

12 Analyst

Table of Contents @TMin 602 @Transform 603 @TRound 605 @Ytd 607 Switchover Dates 609 Examples: 610 Set up a Switchover Date in a Timescale D-List 610 Set up a Switchover Date in a BiF Formula 610 Print or Preview BiF Specifications 611 Chapter 13: Macros

613

Creating and Running Macros 613 Create a Macro using the Wizard 614 Record a Macro 615 Run a Macro 615 Macro Editor 615 Editing Macro Code 615 Editing Macro Variables 617 Start a Macro With Batch Utility Wizard 619 Configure Analyst Security 619 Run the Batch Utility Wizard 619 Using the Command Line to Run a Macro or Batch Job 621 Command Line Options 621 Command Line Examples 622 D-List Macros 627 @DListNew 627 @DListOpen 628 @DListUpdate 629 @ExportToEList 629 @ItemDelete 630 Item Import Macros 631 @DListItemImportCognosPackage 632 @DListItemCopyFromDList 635 @DListItemImportDelimitedText 637 @DListItemImportFileMap 640 @DListItemImportFinance 642 @DListItemImportDCube 644 @DListItemImportIQD 645 @DListItemImportOdbc 646 @RefreshDataWarehouse 649 ODBC Macros 650 Control Macros 650 @Activate 651 @AddLocalPreSelection 651 @CheckAccess 652 @CheckAccessLevel 653 @Close 653 @Delay 653 @FileTranslate 653

User Guide 13

Table of Contents @LibCopy 654 @MacroExecute 655 @Message 656 @PackDir 656 @PackDirSel 657 @Rem 658 @Reset 658 @Run 658 @Save 660 @ShutDown 660 @TestData 660 @UnPackDir 661 D-Link Macros 662 @DLinkActivateQueue 663 @DLinkExecuteInv 663 @DLinkExecSel 664 @DLinkExecute 665 @DLinkExecuteList 666 @DLinkNew 667 @DLinkOpen 668 @DLinkSelectList 668 D-Cube Macros 669 @DCubeCalculate 670 @DCubeClearMask 671 @DCubeCommand 672 @DCubeCreateDSels 673 @DCubeCreateTSels 676 @DCubeDeleteSels 678 @DCubeDeselect 679 @DCubeExport 680 @DCubeIncreaseSelect 683 @DCubeInput 684 @DCubeNew 685 @DCubeOpen 686 @DCubeOpenChooseSel 687 @DCubeOpenNamedSel 688 @DCubeOpenSelect 689 @DCubePage 689 @DCubePageId 690 @DCubePrint 691 @DCubeReselect 693 @DCubeSort 694 @DCubeTranspose 695 @DCubeUpdate 696 @GenerateTransformerModel 697 @Publish 698 @SliceCommand 699 @SliceUpdate 700 File Map Macros 704

14 Analyst

Table of Contents @FMapNew 705 @FMapOpen 705 A-Table Macros 706 @ATabOpen 706 @ATabRefresh 707 @ATabImportCognosPackage 708 @ATabImportDelimitedText 709 @ATabImportFileMap 710 @ATabImportOdbc 710 Chapter 14: A-Tables (Allocation Tables)

713

Example 713 Creating an A-Table 714 Selecting Source and Target for an A-Table 714 Attaching a D-List to an A-Table 718 Add A-Table Entries 719 Add Single Allocation Table Entries 719 Add Multiple Allocation Table Entries 720 Add New Entries for New Dimension Items 721 Add One-to-Many Entries 721 Allocate Entries Using Matching Descriptions 722 One-Sided Allocation Table Entries 723 Insert Items Buttons 723 Select Source and Target Dimension Items 724 Change the Source or Target for an A-Table 725 Managing A-Tables 725 Reorder Allocation Table Entries 725 Show and Hide Dimension Items 726 Change Entry Signs in an Allocation Table 727 How the A-Table Adapts when Dimension Item Lists Change 727 Refresh a Dimension Item List from a Mapped ASCII File 728 Delete A-Table Entries 729 Chapter 15: File Maps

731

Creating a File Map 731 Create a File Map 731 Map Editor Page 1 731 Map Editor Page 2 732 Map Editor Page 3 732 Using the LIB parameter 733 Delimited and Fixed Width ASCII Files 734 Define Columns in an ASCII File 734 Text Qualifiers 737 Special Cases for text qualifiers 738 Date and Text Data in File Maps 738 Import Date Data from a File Map 738 Import Text Data from a File Map into D-List Formatted Cells 740 Follow On 741 What does Follow On do? 742 An alternative view 743 User Guide 15

Table of Contents Which rows will a subheading apply to? 743 Use Follow On and Overlapping Subheadings 745 Drill Down and Follow On 747 Dummy Maps 747 ASCII Files 749 Effects of Changing an ASCII File 749 Effects of Changing Delimited ASCII Files 750 Effects of Changing Fixed Width ASCII Files 752 Effects of Changing the Source ASCII File for a D-Link 752 Chapter 16: Analyst Publish

755

Dimensions for Publish 755 Selecting a Dimension for Publish for Reporting 756 Understanding the Publish Process 757 Table-only Publish Layout 757 Database Object Names 758 Items Tables 758 Hierarchies 759 Export Tables 762 Annotations Tables 763 Metadata Tables 763 Creating a Table-only Publish Layout 766 View Publish Layout 768 Database object names 768 D-Lists 769 D-Cube Data and Export Tables 769 Annotations 769 Metadata 770 Views 771 Creating a View Publish Layout 771 Publishing Using the Command Line 773 Create a DSN for the Database Server 773 Set up Microsoft SQL Server 2000 Desktop Engine as a Database Server 775 Reporting Directly From Publish Tables 775 Generate Framework Manager Model Wizard 776 Configuring Your Environment 777 Create a Set of Framework Manager Models 779 Update a Framework Manager User Model 780 Generate Transformer Model Wizard 780 Configuring Your Environment 781 Generate a Transformer Model 781 Creating PowerCube(s) 782 Model Changes that Impact the Publish Tables 783 Chapter 17: Printing and Previewing

785

Print Setup 785 Previewing 786 Preview Formulas and Details of a D-List 786 Preview a D-Cube 786 Preview D-Cube Summary Information 787 16 Analyst

Table of Contents Printing 788 Print a D-List and Formulas 788 Print a D-Cube 788 Print Nested Macros 789 Print a List of Objects in a Library 789 Print to .csv Files 790 Print Annotations 790 Glossary Index

791

799

User Guide 17

Table of Contents

18 Analyst

Introduction
This document is intended for use with Cognos 8 Planning - Analyst. It helps you understand how to use all of the functionality in Analyst. Cognos 8 Planning provides the ability to plan, budget, and forecast in a collaborative, secure manner. The major components are Analyst and Contributor.

Cognos 8 Planning - Analyst

Analyst is a flexible tool used by financial specialists to define their business models. These models include the drivers and content required for planning, budgeting, and forecasting. The models can then be distributed to managers using the Web-based architecture of Cognos 8 Planning Contributor.

Cognos 8 Planning - Contributor

Contributor streamlines data collection and workflow management. It eliminates the problems of errors, version control, and timeliness that are characteristic of a planning system solely based on spreadsheets. Users have the option to submit information simultaneously through a simple Web or Microsoft Excel interface. Using an intranet or secure Internet connection, users review only what they need to review and enter data where they are authorized. For more information about using this product, visit the Cognos Global Customer Services Web site (http://support.cognos.com).

Best Practices for Cognos 8 Planning

The Cognos Innovation Center for Performance Management provides a forum and Performance Blueprints which you can use to discover new ideas and solutions for finance and performance management issues. Blueprints are pre-defined data, process, and policy models that incorporate best practice knowledge from Cognos customers and the Cognos Innovation Center. These Blueprints are free of charge to existing customers or Platinum and Gold partners. For more information about the Cognos Innovation Center or the Performance Blueprints, visit http://www.cognos.com/ innovationcenter.

Audience
This guide is for both new and experienced Analyst users. Familiarity with financial data is helpful, but not required.

Related Documentation
Our documentation includes user guides, getting started guides, new features guides, readmes, and other materials to meet the needs of our varied audience. The following documents contain related information and may be referred to in this document.

User Guide 19

Introduction Note: For online users of this document, a Web page such as The page cannot be found may appear when clicking individual links in the following table. Documents are made available for your particular installation and translation configuration. If a link is unavailable, you can access the document on the Cognos Global Customer Services Web site (http://support.cognos.com). Logon credentials are available either from your administrator or by request from support.america@cognos. com.

Document
Contributor Administration Guide Manager User Guide Analyst for Microsoft Excel Tutorial Cognos 8 Planning Installation and Configuration Guide

Description
Creating and administering Cognos 8 Planning - Contributor Applications. Using Cognos 8 Planning - Manager Getting to know Cognos 8 Planning - Analyst for Microsoft Excel

Installing and Configuring Cognos 8 Planning Products

Finding Information
To find the most current product documentation, including all localized documentation, access the Cognos Global Customer Services Web site (http://support.cognos.com). Click the Documentation link to access documentation guides. Click the Knowledge Base link to access all documentation, technical papers, and multimedia materials. Product documentation is available in online help from the Help menu or button in Cognos products. You can also download documentation in PDF format from the Cognos Global Customer Services Web site. You can also read PDF versions of the product readme files and installation guides directly from Cognos product CDs.

Getting Help
For more information about using this product or for technical assistance, visit the Cognos Global Customer Services Web site (http://support.cognos.com). This site provides product information, services, user forums, and a knowledge base of documentation and multimedia materials. To create a case, contact a support person, or to provide feedback, click the Contact Us link. For information about education and training, click the Training link.

Printing Copyright Material

You can print selected pages, a section, or the whole book. Cognos grants you a non-exclusive, non-transferable license to use, copy, and reproduce the copyright materials, in printed or electronic

20 Analyst

Introduction format, solely for the purpose of operating, maintaining, and providing internal training on Cognos software.

User Guide 21

Introduction

22 Analyst

What's New?
This section contains a list of new features for this release. It will help you plan your upgrade and application deployment strategies and the training requirements for your users. For information about upgrading, see the Cognos 8 Planning Installation and Configuration Guide. To review an up-to-date list of environments supported by Cognos products, such as operating systems, patches, browsers, Web servers, directory servers, database servers, and application servers, visit the Cognos Global Customer Services Web site (http://support.cognos.com).

New Features in Version 8.3

Listed below are new features since the last release.

Microsoft Excel 2007

This release supports Contributor and Analyst for Excel using Microsoft Excel 2007. For more information about using Analyst or Contributor with Excel, see the Analyst for Microsoft Excel User Guide and Contributor for Microsoft Excel User Guide.

Select Folders in Cognos Connection

This release supports folder selection in Cognos Connection when generating Framework Manager and Transformer models. For more information see the following sections. "Create a Set of Framework Manager Models" (p. 779) "Generate a Transformer Model" (p. 781)

Select Framework Manager Package for D-List Import

This release supports browsing in Cognos Connection folders to select a Framework Manager package for a D-List import. For more information, see "Import D-List Items From a Cognos Package" (p. 130).

User Guide 23

What's New?

24 Analyst

Chapter 1: Analyst Overview

When you open Analyst, you are asked to select a namespace and log on with your user id and (optional) password. Passwords are not case sensitive. If you decide not to use a password, leave the Password box blank. When you close Analyst, if you have any open objects, you are prompted to save them.

Steps
1. Click Start, Programs, Cognos 8, Cognos Planning - Analyst. 2. Choose a namespace and click OK. 3. Type your User ID and [optional] password, and click OK. 4. Select a default library to use for the session. Click OK. 5. To close Analyst, from the File menu, click Exit.

Saving Analyst Data

The data directories are where users store and access data. All users must have full network access rights to their own as well as all other users' data directories. Users store their D-Cubes and other data in directories.You can restrict user access internally within Analyst. We recommend that you do not store your data in the directory where Analyst is installed. Save your data in another directory, preferably on another drive.

Registry Settings
When the application is installed, the registry keys created by the install are written to <HKEY_LOCAL_MACHINE> (HKLM). This allows several users to use the same PC for running Analyst. Writing to HKLM requires power-user rights and access rights to the registry. All registry settings created or changed at runtime are written to <HKEY_CURRENT_USER> (HKCU). Analyst usually writes to HKCU. When trying to read from the registry, it will first look in HKCU to find a specific value. If it doesn't find the value it needs, it defaults to the value in HKLM. Consequently, multiple users can use the same machine but have different registry settings in the HKU/SID, which will keep customized settings from being overwritten by other users. Optional: Changes can be made to the keyboard layout. Only users with power user rights can change these settings. You can also change the Maximum Workspace Size (kb) setting in Cognos Configuration.

User Guide 25

Chapter 1: Analyst Overview

Restart Analyst
Restarting Analyst allows you to select a different default library, or to return to Cognos Planning - Manager if you opened Analyst through Manager.

Steps
From the File menu, click Restart. If you have open objects, you are prompted to save them.

Understanding Analyst
Analyst is very different from Excel. If you have an Excel background, it is important to understanding how Analyst differs from Excel in the key areas.

Formulas in Analyst and Excel Spreadsheets

In a spreadsheet, formulas generally use cell references demonstrated in the following: A4 = B2 + C3 In Analyst, the formulas use D-List item names as demonstrated in the following: Profit = Sales - Costs In a spreadsheet, you can set up formulas that can refer to different rows and different columns (and different pages). In the example above, the cells B2 and C3 are in different rows and columns from the result in cell A4. However, formulas set up in Analyst refer to other items in the same D-List, so formulas always span across the rows or down the columns. This means that a different approach to formulas must be adopted to make complex systems more structured and easier to maintain. When you edit a formula in a spreadsheet, you edit only a single cell at a time. You then must copy the formula so that the relative addresses are updated. In a spreadsheet, you cannot simply add a column or row and automatically expect existing formulas to be copied. However, when you edit a formula in a D-List, that formula affects every cell that uses the D-List and implements the changes without your needing to copy the amended formula. So, for example, a four-dimensional model with twenty items in each D-List and a subtotal at the bottom of each list would contain only four formulas in 400 pages of data. The same model in a series of flat spreadsheets would contain over 20,000 formulas; thus, it would take major effort and discipline to maintain these formulas even with aids such as copy commands and macros. A summary of the major differences between Analyst and spreadsheets is given below.

Spreadsheet Formulas
Cell specific

D-List Formulas
Global

26 Analyst

Chapter 1: Analyst Overview

Spreadsheet Formulas
Spreadsheet specific Use cell references or range names Change by editing a cell then copying

D-List Formulas
Can be used in multiple D-Cubes Use item names Change by editing a single formula: copied automatically

Flexible: can cross-reference different rows, Structured across rows or down columns or pages columns and worksheets Use formulas to refer to a different worksheet Thousands in a large spreadsheet @function ( ) Use D-Links to refer to a different D-Cube

Few are needed Built in Functions (BiFs)

Using LIB and LIBNO Parameters

System parameters are used to insert information into object names, descriptions, paths. System parameters can be used when creating file maps and D-Links. The table below outlines the system parameters used in Analyst.

System Parameter
{LIB}

Description
Inserts the current library path of the object where {LIB} is used. Can be used in file maps, import D-Links, and the @DCubeExport macro.

{LIBNO}

Inserts the current library number of the object where {LIBNO} is used. Can be used in file maps.

Other Differences
Multi-page spreadsheets generally are only three-dimensional, whereas D-Cubes can contain four, five, or even six dimensions. Some spreadsheets now can be pivoted so page labels become column headings and vice versa. The options for viewing D-Cubes go further than this. The rows, columns, and pages can be interchanged. Spreadsheets generally use cell references for formulas and store the calculations in the worksheet. D-Cubes, however, do not store the formulas. Rather, the formulas are stored in D-Lists as separate entities. The practical effect of this is that one set of formulas can be used in many User Guide 27

Chapter 1: Analyst Overview different D-Cubes. D-List formulas use the same names throughout, so a formula is not dependent on a relative cell reference or the position of a cell. In spreadsheets, the arithmetic is generally one way. Data is typed in designated cells and the results are shown in other cells. Any attempt to type data in formula cells results in an error. In D-Cubes, the arithmetic is two-way: Targets can be set by typing data in a formula cell and splitting it to its component parts according to predefined rules. For example, you could enter a budget for the full year, and the program would split the annual figure into months by allocating it pro rata across a given seasonality profile. This two-way arithmetic is known as breakback. To refer to a different worksheet, spreadsheets generally use formulas. To refer to a different D-Cube, D-Cubes use D-Links rather than formulas.

Multi-User Object Access

At any one time, only one person is allowed to write to an object. Suppose two people have been assigned write-access to the same D-Cube. The first person who opens the D-Cube will open it in write mode and can save any changes to the original. The second person to open the D-Cube will be told that the D-Cube is currently being updated. They will be permitted to open the D-Cube in read-only mode. Any changes that are made by the second person will not be saved although they are permitted to save a copy with a different name. This can only be used later if a D-Link is set up to overwrite the original with the copy. Suppose the second person wants to make changes to the original. He or she must contact the first person and request that they save what they are doing and switch to read-only mode. This will allow the second person to open (or reopen) the D-Cube in write-mode. He or she can then make changes to the original D-Cube and save it. A similar situation exists for any object where two or more people want to make changes to an object simultaneously. Any object can be opened in read-only mode to allow another user to update it elsewhere. However, after you have switched to read-only mode, you can not revert to write-mode without closing and reopening the object. This ensures that you are always working on the latest version.

Analyst Samples
Sample models are provided with Cognos Planning. Samples illustrate key features in these products. Samples are installed to the following location for English installation _location\samples\en\Planning. For French and German language installs, the path would be ...\samples\fr\Planning and ...\samples\ de\Planning. They can be accessed directly from Cognos Planning - Analyst without any further configuration if the system administrator has installed them. The following table lists the samples available in Cognos Planning. This is not necessarily an exhaustive list. Visit the Cognos Global Customer Service Web site (http://support.cognos.com) for more information. 28 Analyst

Chapter 1: Analyst Overview We recommend that you do not edit and save any of these samples directly. Instead, copy the required D-Lists, including any formats such as D-List formats, into another library, and then rebuild the D-Cubes. You may want to use other dimensions such as Time, as appropriate.

Name
tutorialgo

Planning Component
Analyst

Description
A lightweight model used with the Analyst Tutorial and Analyst for ExcelTutorial to demonstrate key Analyst functionality Used to demonstrate and test much of the Analyst functionality. Provides working examples of all Built in Functions. Contains a macro which runs D-Links to D-Cubes in either Analyst or Contributor in a series of steps, each targeting a small slice or chunk of the target D-Cube, and thus requiring far less memory to execute the link.

great outdoors analyst

Analyst

bif

Analyst

slice_update

Analyst

Tutorialgo
The Analyst Tutorial demonstrates how to create a simple Analyst model. The tutorialgo library is the finished model. It is designed to introduce users to the concepts of Analyst. In particular, the principles of the D-List, D-Cube and D-Link. See the Analyst Tutorial for more information. Analyst for Excel tutorial also uses this library, see the Analyst for Microsoft Excel Tutorial for more information. The tutorialgo model does not make full use of the functionality available in Analyst. For more functionality, use the great outdoors analyst model.

Great Outdoors Analyst

The great outdoors analyst sample is designed to illustrate many of the features and functionality available in Analyst. It is an example of a plan of expenditure of a fictional business. The structure of the great outdoors analyst model is described in the following sections.

Depreciation
The Depn policy D-Cube holds the asset life and depreciation methods for all the different asset types.

User Guide 29

Chapter 1: Analyst Overview The Asset purchases D-Cube allows entry by division, by budget version of the cost, asset type, month of purchase, and month to start depreciation. The Depreciation D-Cube allows calculation of depreciation on new asset purchases, and combines this with depreciation on existing items. This is typically imported from a fixed asset register to determine appreciation charge.

Sales
The Price and cost D-Cube holds sales price and unit cost by product and by version. The Sales plan D-Cube determines the calculation of a growth margin from its elements by product, channel, division, month, and version.

Salaries
The Base Salaries D-Cube makes the assumption that individual salaries are based on grade. It holds the base salary by grade, division, and, version. The Salary plan D-Cube determines the salary by individual, version, and by month based on their division, grade, and month they are due an increase. The start date has been included for information purposes. It is not part of the calculation of the salary, although this functionality could be included if required.

Expenses
The Expenses D-Cube has links from Salary Plan and Commissions to import the appropriate data. Additionally the Expenses D-Cube holds details of the overhead expenditure. The overhead expenditure is planned at annual level and breakback functionality is then used to apportion it to months appropriately. The OH adjust D-Cube holds the annual base data by overhead item, division, and month. It allows a percent change to be applied to the base amount to provide an adjusted amount. The OH profiles and Profile types D-Cubes enable the adjusted overhead values to be apportioned into the appropriate months depending on the profile to be used and the monthly structure of that profile. The Commissions D-Cube takes the growth sales revenue and applies the appropriate commission percentage to determine the commission charge by division, month, and version.

Income Statement
The Franchise rev D-Cube holds the imported franchise revenue by division, month, and version. The Inc Statement D-Cube is a summary D-Cube combining the summary level from the other D-Cubes. In addition, it allows for below the line expenditure to be entered, by division.

Miscellaneous
Additionally, this sample includes the following: Csv files that contain the base data D-Links to import the data

30 Analyst

Chapter 1: Analyst Overview Macros to help with model maintenance Manager screens have been provided to aid the understanding and usability of the sample. They consist of a front page, two flowcharts, and some sample screens to manage and maintain the model.

The BiF Library

The BiF library provides working examples of all Built in Functions. It is optionally installed with the software. This self-contained BiF library may be accessed using Cognos Planning - Analyst, however a Cognos Planning - Manager front end has been provided to simplify navigation. There are four reports included in the BiF library. They are linked together and provide links to the appropriate D-Cubes. Where appropriate, graphs are provided to further explain the impact of the different methods available. The BiF library contains a D-Cube for each BiF. Each D-Cube in the BiF library consists of a minimum number of dimensions, enough to demonstrate functionality only. When working with your own D-Cubes, it is likely that they will contain more dimensions than those demonstrated in the library. Where ever possible, the D-Cube data supplied in the BiF library mirrors the Online Help D-Cube data examples to further integrate the BiF library and the Online Help. D-Cubes in the BiF library should therefore not be saved following any changes. Where appropriate, annotations have been provided to further explain the data provided.

The Slice Update Sample

The Slice Update sample is supplied as an optional download from the Cognos Global Customer Services Web site (http://support.cognos.com). The slice_update sample contains a macro which runs D-Links to D-Cubes in either Analyst or Contributor, in a series of steps each targeting a small slice or chunk of the target D-Cube. This means that far less memory is required to execute the link. To ensure the whole D-Cube is updated, a series of slices is required, instead of setting these up manually (create a looping macro to run the D-Link to each defined slice sequentially). This sample model contains examples of macros which allow the target D-Cube to be sliced on either one, or two dimensions in any number of steps.

Differences between Analyst and Contributor

When using slice_update, consider the differences between Analyst D-Cubes and Contributor cubes as targets. If Analyst is your target, then the D-Cube must be updated using a @DCubeUpdate command. The slice_update does not operate if a @DLinkExecute command is used. If Contributor is the target, then the commands @DLinkExecute or @DLinkExecuteList can be used in the macro. Where Contributor is the target, you must store the elements making up the looping macro in a separate library from the library in which the Contributor application is based. This is because the

User Guide 31

Chapter 1: Analyst Overview Steps cube does not need to contain the e.List, but must have an internal D-Link. Contributor does not allow internal D-Links if the cube does not contain the e.List. This sample has been set up so that it will work in Analyst. For information on using it with Contributor, see (p. 34). There are three parameters in the @SliceUpdate macro:

Lists
A list of the D-Lists which are to be used as slice dimensions.

Lookup
A slice of a D-Cube which stores data about the dimensions being sliced on. When Analyst is the target, the rows D-List of this D-Cube must contain items that have the same names as some or all of the items in the D-Lists in the target D-Cubes on which you are slicing. When Contributor is the target, the rows dimension of this cube must contain the same items as the dimension being sliced on in the Contributor cube, and it must also have exactly the same name.

Criteria
The basis for deciding which elements of the target D-Cube should be targeted when the D-Link is run.

The D-Cubes
The Target Cube Analyst1 D-Cube has the dimensions: Single Item, Target, sources, Divisions, and Versions. The Target Cube Analyst2 D-Cube has the dimensions: Single Item, Target, sources, European Areas, and Versions. The European Areas D-List contains some of the items in the Divisions D-List but not all of them. There is one link targeting each D-Cube. In each case it is included in the @DCubeUpdate list. When the D-Cubes are updated, either the Versions dimension, the Divisions/European Areas dimension, or both could be used to define the slices.

Example 1 - A One Dimensional Slice on the Versions D-List

The Steps slice dimension 1 D-Cube was updated to contain the same items as the Versions D-List. The update steps have been defined as follows 1st step 2nd step 3rd step 4th step Version 4 and Version 5 Version 2 Empty Version 6.

32 Analyst

Chapter 1: Analyst Overview The empty step is left in to illustrate that the macro will not stop if one step is empty. Versions 1, 3, and 7 are not set to be updated. The 'Target Cube Analyst 1' and 'Target Cube Analyst 2' D-Cubes are all zero. The 'Update macro target analyst' macro runs the D-Cube update steps for both D-Cubes. The single dimension slice update is defined in the 'Template Macro 1' macro. The Versions dimension is defined as the dimension on which to slice. Any item from the Versions D-List is targeted when the D-Link is run, if it is defined as the 1st step in the Current Step column of the Slice Dimension 1 D-Cube. The update steps were defined in a separate column of this same D-Cube.

Template Macro Loop 1

When the 'Template Macro Loop 1' macro is run, the following process takes place. The data input in the Specify Step column of the 'Slice Dimension 1' D-Cube specifying which version is updated in each step is transferred by D-Link to the Current Step column. The macro that updates the two D-Cubes runs under the control of the slice update mechanism so that only Versions defined as 1st Step are targeted, in this case Version 4 and Version 5. A command in the macro deducts 1 from each item in the Current Step column of the 'Steps slice dimension 1' D-Cube. Any item which was previously 2nd Step now becomes 1st Step. The macro tests the data in the Current Step column. If any items greater than 1 remain it restarts itself from the beginning, otherwise it stops.

When the macro is complete, in the Target D-Cubes, Versions 2, 4, 5 and 6 now contain a number 1 as they have been targeted by the link.

Example 2 - A two dimensional slice on Versions and Divisions/European Areas.

If the D-Cubes you are targeting are very large, you may want to slice them in two dimensions. When using this macro with the sample model, ensure that both target D-Cubes are set to zero. The two dimensional looping macro illustrates this process. It uses the same slices for the Versions D-List as defined in example 1. Additionally, in the 'Steps slice dimension 2' D-Cube, steps for the Divisions/European Areas are defined. Americas and Central Europe are to be updated as Step 1. Southern Europe is to be updated as Step 2. The slice update is defined in the 'Template Macro 2' macro. Note that both Divisions and European Areas D-Lists are included in the List of Lists. Because the 'Template Macro 2' macro has been set up as a nested macro, the update will take place as follows. All of the processes defined in the first example will take place for Americas and Central Europe first. These processes are repeated for Southern Europe. User Guide 33

Chapter 1: Analyst Overview When the macro has finished, only cells in Americas, Central Europe, or Southern Europe and Version 2, 3 5 or 6 will contain a 1. This means that only very small slices of the D-Cube have been updated in each round.

Steps to Adapt the Template for a User Model

Adapt the template for a user model to slice a D-Cube into two dimensions. 1. Decide which target dimensions in your model are to be used for slicing. 2. Update the D-Lists 'Slice Dimension 1' and 'Slice Dimension 2' (only for a two-dimensional slice) with items from your D-Lists. 3. Open the 'Template Macro 1' macro and replace the second command line with your own update macro. 4. Edit the SliceUpdate parameters so that the List of Lists contains your D-Lists. 5. Set the update steps in the 'Steps slice dimension 1' and 'Steps slice dimension 2' D-Cubes, if applicable. Running the macro DCO Steps 1 or DCO Steps 2 will open the correct slice. 6. Run either 'Template macro loop 1' or 'Template macro loop 2', depending on whether you set up a one or two dimensional slice.

Using the Slice Update Macro with Contributor

When using a Contributor target, it is only possible to have one D-List in the List of Lists. This could be your Contributor e.List but does not have to be. If you have several dimensions containing similar items on which you wish to slice, as in the case of Divisions/European Areas, you must set up separate slice update Lookup cubes for each of them.

Steps
1. Rename the 'Steps slice Dimension 1' D-Cube to exactly the same name as your Contributor dimension. 2. Update the D-List with all the items contained in the Contributor dimension. 3. Edit the SliceUpdate parameter in 'Template macro 1' so that the list of lists contains only this D-List. 4. Replace the second command line with your own update macro. 5. Set your update steps in the 'Steps slice Dimension 1 cube. Running the 'DCO Steps 1' macro opens the correct slice. 6. Run the 'Template macro 1' macro.

Customizing the Analyst Toolbar

Customize the Analyst toolbar to add user-created menus and buttons.

34 Analyst

Chapter 1: Analyst Overview

Use Custom Menus

User defined menus are added before the Window and Help menus on the menu bar. When using custom menus, you must create a .txt file.

Steps
1. From the Tools menu, click Options. 2. Click the Custom tab. 3. In the Custom Menu File text box, type the path of the custom menu, or browse for the file. 4. Click OK. 5. You are prompted to restart Analyst. 6. For the changes to take effect, click Yes. Analyst closes and re-opens.

Example of a custom menu file

;Custom menu for Cognos 1Cognos &Incorporated 2&Lists 3&Timescale::M|600102 DLO-periods 3&Versions::M|600102 DLO-Budget Versions 3&Profit and Loss Accounts::M|600102 DLO-Accounts 2&Update 3&Profit and Loss::M|600102 DCU-Accounts When creating custom menus, only macros (p. 613) can be used. For example, M|600102 DLO-Accounts runs an @OpenDList macro named DLO-Accounts from library number 600102. When a line begins with a semicolon (;), it is a comment. Otherwise, the first character must be a digit specifying the Level of the menu (item). The level may be 1, 2, or 3. Level 1 is a menu on the main menu bar, level 2 is a submenu of level 1 items, and level 3 is a submenu of level 2. You must start with a level 1 item, that will appear on the analyst toolbar. Following this, you use a level 2 item to define the first sub-menu step. If this level 2 item has a sub-menu, you follow it with level 3 steps until the sub-menu is fully defined. You then proceed to use another level 2 item, because it is the second step of the main menu. This can again be followed by level 3 items if needed. If you include another level 1 item, it will also appear on the toolbar and can be followed by sub-menus of its own. Continue until your whole menu is defined. Immediately following the digit defining the level up to the first colon (:), is the caption to go on the menu (item). If one character is preceded by an ampersand (&), this character is underlined and can be used to select the item when the menu is active. From the first to the second colon is the tip text for the menu (item); currently tip texts are not displayed for the menus and are used only as comments in the menu definition file.

User Guide 35

Chapter 1: Analyst Overview For a menu item, the action code follows the second colon. The only documented action code is "M|" for a macro call. Other action codes exist but currently are for internal use only. Macros are defined by a numeric library number followed by the full macro name. Note: Only use letters after the ampersand (&) or Analyst will not function. The character following the ampersand (&) must be a letter of the English alphabet. If you use other characters, Analyst will not work on start-up.

Create Custom Toolbar Buttons

You can create custom toolbar buttons in Analyst that, when clicked, will run macros (p. 613). The user-defined toolbar buttons display on the toolbar before the execute button (which appears only when there are unprocessed entries in a D-Cube). When you create the custom toolbar file, you must save it as a text (.txt) file. For example, a sample toolbar .txt file is C:\Program Files\Cognos\YourDirectory\CustomToolbar. txt. The layout of a custom toolbar text file to add a button which opens a D-List called 'Accounts' in library number 600102 would appear as follows: ;custom toolbar file Open Accounts D-List,C:\Program Files\Cognos\YourDirectory\DLOPEN. bmp,10,M|600102 DLO-Accounts If a line begins with a semicolon (;), it is a comment. Otherwise, each record must contain the following four fields, separated by commas. A description, which is also used as a tip on the button. The full path of the bitmap file to use for the button, for example, C:\Program Files\Cognos\ YourDirectory\DLOPEN.bmp. Offset in pixels from the previous button, 10 in this example. An action code to run a named macro. For example M|600102 DLO-Accounts runs an @OpenDList macro named DLO-Accounts from library number 600102.

Note: When creating the Custom Toolbar text (.txt) file, ensure that there are no spaces between the commas separating the four fields.

Steps
1. Create the custom toolbar text (.txt) file. 2. Create (or use an existing) a toolbar button saved as a bitmap (.bmp) file. 3. From the Tools menu, click Options. 4. Click the Custom tab. 5. In the Custom Toolbar File text box, type the path of the custom toolbar, or browse for the file, and then click OK. 6. Click Yes to restart Analyst.

36 Analyst

Chapter 2: Administration
There are a number of administrative tasks that must be performed on a regular basis. A necessary part of application administration is the care and maintenance of the Analyst database. As a regular part of these efforts, you must: view and edit Analyst workspace settings(p. 37) set FileSys.ini file (p. 38) rebuild index files (p. 39) refresh references to objects (p. 39) validate D-Lists (p. 39) close ODBC links (p. 40) manage memory (p. 40) manage masks (p. 40) administer users (p. 40) set configuration settings (p. 40) administer groups (p. 41)

Viewing and Editing Analyst Workspace Settings

You can view and edit your Analyst workspace settings. Their is a separate Cognos configuration for every computer where Analyst is installed that controls the settings on that computer. Use Cognos Configuration to change the Analyst Workspace settings. Edit and view the workspace setting from within Cognos Configuration. You can also view the workspace settings from the Analyst Tools, Options menu.

Steps to Edit and View Workspace Settings

1. Start Cognos Configuration. 2. In the Explorer window, under Environment, click Planning. 3. Under Planning - Component Properties, Analyst maximum workspace size in KB, Value, enter a workspace value in KB. 4. From the File menu, click Save.

User Guide 37

Chapter 2: Administration The amount of memory you specify can be a value between 64000 and 2000000, and the memory is allocated as it is needed up to the limit you set.

Steps to View the Workspace Setting From Analyst

1. In Analyst, from the Tools menu, click Options. 2. Click the General tab. 3. In the Maximum Workspace Size (kb) box, you can view the current maximum workspace setting.

Creating Planning Tables

The first time Planning is run, a check is run to see if any Planning tables exist in the Planning content store. If not, you are prompted to create them. You can either create them directly or select the option to create a script which can be modified and run by a Database Administrator (DBA). You also have the option to specify the path to the filesys.ini file. You change this setting if the default path is not used. The filesys.ini file is a control file that contains file paths for the Libs.tab, Users.tab, and Groups.tab that control the specific library and user setup. You can edit the filesys. ini path by selecting Tools, Edit FileSys.Ini path.

Set Filesys.ini
The filesys.ini file is the main control file that is referred to when the program starts. You can specify the pathnames of the Libs.tab, Users.tab, and Groups.tab that control your specific library and user set-ups. You can edit the location of the filesys.ini file from Analyst, and from the Contributor Administration Console.

Steps in Analyst
1. From the Tools menu, click Options. 2. Click the General tab. 3. In the Active Filesys.ini file box, click type the path of the filesys.ini file or click Browse to locate the file manually.

Steps in the Contributor Administration Console

1. From the Tools menu, click Edit FileSys.Ini path. 2. Type or browse to the path of the filesys.ini.

38 Analyst

Chapter 2: Administration

Rebuild Index Files

When copying or moving large models using Windows Explorer, the index files can become corrupt. Index files are system-generated tables that list all objects in a library. Their DOS names are given the suffixes .ho, .d1 and .d2, and, on rare occasions, they may need to be rebuilt and then refreshed.

Step
From the File menu, click Administration, Rebuild Index Files. The index files will be rebuilt from DOS pathnames of objects in the current library.

Refresh References
Because objects have references to other objects - for example, a D-Cube refers to its D-Lists, a D-Link refers to its source and target D-Cubes, and a selection refers to its D-Cube and D-Lists, and because models can become very large and complicated, references may become corrupt. On rare occasions, you may need to refresh these references.

Step
From the File menu, click Administration, Refresh References. The references to other objects in the current library are refreshed. If any libraries on the system are ever offline, and work is done on the remaining libraries, it will be necessary to refresh references on these libraries when they come back online. Also, if work has been done on the libraries while offline, all remaining libraries must be refreshed when it all comes online again.

Validate D-Lists
This function enables you to check the syntax of every formula in every D-List in the current library.

Step
From the File menu, click Administration, Validate D-Lists. Cognos Planning - Analyst checks the validation of each calculation contained in every D-List.

DOS File Names

The program automatically generates a DOS file name for each object you create. Each file will have a suffix indicating which type of object it is. Never attempt to copy or move files in DOS or Windows Explorer because it can create problems with the references between objects and the system.

User Guide 39

Chapter 2: Administration

Close ODBC Links

If you select the option to keep an ODBC link open at the time of setting it up, you can go back and close the online links with a database.

Step
From the File menu, click Close ODBC.

Configuration Settings
You can alter the configuration settings. These control the path to the start-up control file, the maximum memory usage, the undo/redo facility, and the customized menu options.

Steps to use a custom menu file

1. From the Tools menu, click Options. 2. Click the Custom tab. 3. In the Custom Menu File text box, type the path of the custom menu. 4. Click OK. 5. For changes to take effect, restart Analyst.

Steps to change the keyboard layout

1. From the Tools menu, click Options. 2. Click the Language tab. 3. In the Keyboard Layout box, select a language. 4. Click OK.

Steps to change the number of undos and redos

1. From the Tools menu, click Options. 2. Click the Undo tab. 3. Select or clear the Enable Undo/Redo check box to enable or disable the feature. Note: By default, this is disabled because it takes up valuable memory. 4. Type the stack size of undo in the Undo Stack Size (excluding D-Cube data) box. StackBytes is set to a default of 1024 KB (1 MB). This controls the amount of memory allocated to undoing any operation apart from data entry in cells in a D-Cube. Note: This should not be set higher than the workspace setting. Because this is used for small objects like D-Lists, macros, and D-Links, it does not require a large stack size.

40 Analyst

Chapter 2: Administration 5. Type the stack size of D-Cube data undo in the D-Cube Data Undo Stack Size box. CubeStackBytes in the CP section of the registry or in Cognos.ini is the amount of memory that Analyst uses for storing the cells that are to be undone/redone. These are measured in kilobytes (that is, 1024 KB = 1 MB). The rule of thumb is that 8 bytes is needed for each cell that is to be undone/redone. For example if the D-Cube Data Undo Stack Size = 1024, 128,000 cells can be undone: 1024000 / 8 = 128,000. Thus a 10,000 cell D-Cube selection could be undone 12 times, whereas a 128,000 cell D-Cube selection can be undone only once. This assumes that the Maximum Undoable View Size is increased to allow it. When calculating the number of levels of undo, it is the total number of cells in the selection that counts, not the number of cells that actually have changed. Note: This does not use workspace. It uses a machine's extra PC RAM, and will therefore be restricted by the amount of available RAM and the number of applications that are running. 6. Type a value for the maximum undoable size in the Maximum Undoable View Size (MaxViewCells*8) box. This is the setting that is used to filter what goes into the D-Cube Data Undo Stack Size. By default, this is set to 128, which means a D-Cube selection of more than 16,000 cells cannot be undone (128,000 bytes/8 bytes per cell = 16,000 cells). For example. If you have a large selection from one D-Cube and many small selections from other D-Cubes, you may not be interested in undoing operations on the large D-Cube. You could set the limit to 10000 cells, for instance, so the undo/redo engine will ignore selections larger than 10000 cells (avoiding taking snapshots of them). Note: For very large D-Cubes, if memory is limited, you may want to disable the undo/redo function.

Step to change MAXWS and keyboard settings

Modify the MAXWS and keyboard layout settings are stored in the HKEY_Local_Machine part of the registry. Note: Contact your system administrator if you do not have access.

Steps to locate ODBC sources

1. From the File menu, click Administration, Locate ODBC-Sources. 2. Select the ODBC source required from the drop down box, or click All to search for all ODBC sources. 3. Select the library in which to search, or click All to search in all libraries. 4. Select the check boxes to search for D-lists, D-Links or both. 5. Click Search Now to display a table of objects using the source(s). You may filter on the object name or the table name to limit the number of objects displayed. 6. Click Highlight and specify only the objects that you want to appear.

User Guide 41

Chapter 2: Administration 7. From the table, right-click to open an object, or print or preview the list of objects.

Steps to locate Built in Functions

1. From the File menu, click Administration, Locate Built in Function. 2. Select a BiF from the drop-down box, or click All to search for all BiFs. 3. Select the library in which to search, or click All to search in all libraries. 4. Click Search Now to display a table of objects using the source(s). You may filter on the object name or the table name to limit the number of objects displayed. 5. Click Highlight and specify only the objects that you want to appear. 6. From the table, right-click to open an object, or print or preview the list of objects.

42 Analyst

Chapter 3: Objects
Objects are the basic building blocks used to create models in Cognos Planning - Analyst.

Objects include:
D-Lists (p. 215) D-Cubes (p. 147) D-Links (p. 215) A-Tables (Allocation Tables) (p. 713) File Maps (p. 731) Macros (p. 613) Formats (p. 109) Selections (p. 197) Libraries (p. 301)

Add a Description to an Object

Descriptions and owner's notes can be attached to various objects.

Steps
1. Open the object. 2. From the File menu, click Summary Info. 3. Click the General tab and type an owner's note or description in the Notes box. 4. Click OK. 5. Save and close the object to ensure the notes are kept.

Reveal Object Name from DOS Filename

You can show the Analyst object name from the DOS filename and vice-versa.

Step
Select File, Administration, File to Object then select a file name.

User Guide 43

Chapter 3: Objects The object name and the Windows path are revealed.

44 Analyst

Chapter 4: Security
Cognos 8 security is designed to meet the need for security in various situations. You can use it in everything from a proof of concept application where security is rarely enabled to a large scale enterprise deployment. The security model can be easily integrated with the existing security infrastructure in your organization. It is built on top of one or more third-party authentication providers. You use the providers to define and maintain users, groups, and roles, and to control the authentication process. Each authentication provider known to Cognos 8 is referred to as a namespace. In addition to the namespaces that represent the third-party authentication providers, Cognos 8 has its own namespace named Cognos. The Cognos namespace makes it easier to manage security policies and deploy applications. For more information, see the Cognos 8 Security and Administration Guide.

Cognos Namespace
The Cognos namespace is the Cognos 8 built-in namespace. It contains the Cognos objects, such as groups, roles, data sources, distribution lists, and contacts. During the content store initialization, built-in and predefined security entries are created in this namespace. You must modify the initial security settings for those entries and for the Cognos namespace immediately after installing and configuring Cognos 8. You can rename the Cognos namespace using Cognos Configuration, but you cannot delete it. The namespace is always active. When you set security in Cognos 8, you may want to use the Cognos namespace to create groups and roles that are specific to Cognos 8. In this namespace, you can also create security policies that indirectly reference the third-party security entries so that Cognos 8 can be more easily deployed from one installation to another. The Cognos namespace always exists in Cognos 8, but the use of the Cognos groups and roles it contains is optional. The groups and roles created in the Cognos namespace repackage the users, groups, and roles that exist in the authentication providers to optimize their use in the Cognos 8 environment. For example, in the Cognos namespace, you can create a group named HR Managers and add to it specific users and groups from your corporate IT and HR organizations defined in your authentication provider. Later, you can set access permissions for the HR Managers group to entries in Cognos 8.

User Guide 45

Chapter 4: Security

Authentication Providers
User authentication in Cognos 8 is managed by third-party authentication providers. Authentication providers define users, groups, and roles used for authentication. User names, IDs, passwords, regional settings, personal preferences are some examples of information stored in the providers. If you set up authentication for Cognos 8, users must provide valid credentials, such as user ID and password, at logon time. In Cognos 8 environment, authentication providers are also referred to as namespaces, and they are represented by namespace entries in the user interface.

Cognos 8 does not replicate the users, groups, and roles defined in your authentication provider. However, you can reference them in Cognos 8 when you set access permissions to reports and other content. They can also become members of Cognos groups and roles. The following authentication providers are supported in this release: Active Directory Server Cognos Series 7 eTrust SiteMinder LDAP NTLM SAP

You configure authentication providers using Cognos Configuration. For more information, see the Installation and Configuration Guide.

Multiple Namespaces
If multiple namespaces are configured for your system, at the start of a session you must select one namespace that you want to use. However, this does not prevent you from logging on to other namespaces later in the session. For example, if you set access permissions, you may want to reference entries from different namespaces. To log on to a different namespace, you do not have to log out of the namespace you are currently using. You can be logged on to multiple namespaces simultaneously. Your primary logon is the namespace and the credentials that you use to log on at the beginning of the session. The namespaces that you log on to later in the session and the credentials that you use become your secondary logons. When you delete one of the namespaces, you can log on using another namespace. If you delete all namespaces except for the Cognos namespace, you are not prompted to log on. If anonymous access is enabled, you are automatically logged on as an anonymous user. If anonymous access is not enabled, you cannot access the Cognos Connection logon page. In this situation, use Cognos Configuration to enable anonymous access.

46 Analyst

Chapter 4: Security

Deleting or Restoring Unconfigured Namespaces

You can preserve namespaces and all their contents in the content store even if they are no longer configured for use in Cognos 8. When a namespace is not configured, it is listed as inactive in the directory tool. An inactive namespace is one that was configured, but later deleted in Cognos Configuration. The namespace can be deleted from the content store by members of the System Administrators role. You cannot log on to an inactive namespace. If a new version of Cognos 8 detects a previously configured namespace that is no longer used, the namespace appears in the directory tool as inactive. You can configure the namespace again if you still require the data. If the namespace is not required, you can delete it. When you delete a namespace, you also delete all entries in My Folders that are associated with that namespace, and their contents. An active namespace cannot be deleted, but can be updated. To recreate a namespace in Cognos Configuration, you must use the original ID of the namespace. For information about configuring and recreating namespaces, see the Installation and Configuration Guide.

Delete an Inactive Namespace

If a namespace was removed from Cognos Configuration and is no longer required, a member of the System Administrators role can delete it permanently in the directory tool. Deleting a namespace also deletes all the entries in My Folders that are associated with the namespace. To access the directory administration tool, you must have execute permissions for the directory secured feature and traverse permissions for the administration secured function.

Steps
1. In Cognos Connection, in the upper-right corner, click Launch, Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. If the namespace you want to delete does not have a check mark in the Active column, it is inactive and can be deleted. 3. In the Actions column, click the delete button. If the namespace is active, the delete button is not available. The namespace is permanently deleted. To use the namespace again in Cognos 8, you must add it using Cognos Configuration.

Users, Groups, and Roles

Users, groups, and roles are created for authentication and authorization purposes. In Cognos 8, you can use users, groups, and roles created in third-party authentication providers, and groups

User Guide 47

Chapter 4: Security and roles created in Cognos 8. The groups and roles created in Cognos 8 are referred to as Cognos groups and Cognos roles.

Users
A user entry is created and maintained in a third-party authentication provider to uniquely identify a human or a computer account. You cannot create user entries in Cognos 8.

Information about users, such as first and last names, passwords, IDs, locales, and email addresses, is stored in the authentication providers. However, this may not be all the information required by Cognos 8. For example, it does not specify the location of the users' personal folders, or format preferences for viewing reports. This additional information about users is stored in Cognos 8, but when addressed in Cognos 8, the information appears as part of the external namespace.

Access Permissions for Users

Users must have at least traverse permissions for the parent entries of the entries they want to access. The parent entries include container objects such as folders, packages, groups, roles, and namespaces. Permissions for users are based on permissions set for individual user accounts and for the namespaces, groups, and roles to which the users belong. Permissions are also affected by the membership and ownership properties of the entry. Cognos 8 supports combined access permissions. When users who belong to more than one group log on, they have the combined permissions of all the groups to which they belong. This is important to remember, especially when you are denying access. Tip: To ensure that a user or group can run reports from a package, but not open the package in a Cognos studio, grant the user or group execute and traverse permissions on the package.

Groups and Roles

Users can become members of groups and roles defined in third-party authentication providers, and groups and roles defined in Cognos 8. A user can belong to one or more groups or roles. If users are members of more than one group, their access permissions are merged. Groups and roles represent collections of users that perform similar functions, or have a similar status in an organization. Examples of groups are Employees, Developers, or Sales Personnel. Members of groups can be users and other groups. When users log on, they cannot select a group they want to use for a session. They always log on with all the permissions associated with the groups to which they belong. Roles in Cognos 8 have a similar function as groups. Members of roles can be users, groups, and other roles. The following diagram shows the structure of groups and roles.

48 Analyst

Chapter 4: Security

Group

Role

User

Group

User

Group

Role

You create Cognos groups and roles when you cannot create groups or roles in your authentication provider groups or roles are required that span multiple namespaces portable groups and roles that can be deployed are required In this case, it is best to populate groups and roles in the third-party provider, and then add those groups and roles to the Cognos groups and roles to which they belong. Otherwise, you may have trouble managing large lists of users in a group in the Cognos namespace. you want to address specific needs of Cognos 8 administration you want to avoid cluttering your organization security systems with information used only in Cognos 8

Cognos 8 Planning Roles

There are two predefined roles for Cognos 8 Planning: Planning Rights Administrators This role enables you to access Contributor Administration Console, Analyst, and all associated objects in the application for the first time following installation. You can then change the roles, groups, and users who can access the Contributor Administration Console and to Analyst. Planning Contributor Users This is the default role for users who want to access the Contributor Web client, Contributor for Excel, or Analyst. However, anyone can be assigned rights to use the Contributor Web client, or Contributor for Excel regardless of whether they are a member of the Planning Contributor Users role. Analyst users must be members of the Planning Contributor User role. Note: You do not have to use these roles, they can be deleted or renamed. If you decide not to use the predefined roles, you must assign the access permissions and capabilities required by Cognos 8 Planning to other groups, roles, or users.

Capabilities
Capabilities are secured functions and features. If you are an administrator, you set access to the secured functions and features by granting execute permissions for specified users, groups, or roles. Users must have at least one capability to be accepted through the Cognos Application Firewall.

User Guide 49

Chapter 4: Security The Planning Contributor Users role has the Planning Contributor capability by default. If you do not want to use this role, you can assign the capability to any groups, users, or roles that you create to replace this role by giving execute permissions to the appropriate members. The Planning Rights Administrators role has the Planning Rights Administration capability by default. To assign this capability to groups, users, or roles, you must give execute permissions to the appropriate members. You must also give members permissions to traverse the Administration folder. Tip You change capabilities through Cognos Administration, by clicking the Security tab. For more information, see "Securing Functions and Features" in the Administration and Security Guide.

Capabilities Needed to Create Cognos 8 Planning Packages

You can create a Planning Package during the Go to Production process, giving users access to Cognos 8 studios from the Contributor application and enabling users to report against live Contributor data using the Planning Data Service. To do this, the Planning Rights Administrators role must be granted the Directory capability. Members of the System Administrator role are automatically granted this capability, but Planning Rights Administrator members are not.

Setting up Security for a Cognos 8 Planning Installation

You must set up security for a Cognos 8 Planning installation. To configure security for Cognos 8 Planning, do the following: Using Cognos Configuration, configure Cognos 8 to use an authentication provider Using Cognos Administration add Contributor Administration Console and Analyst administrators to the Planning Rights Administrators role add Contributor application members and Analyst users to the Planning Contributor Users role enable Planning Roles in Cognos 8 restrict access to the everyone group create additional roles or groups for Cognos 8 Planning (optional) Note: We recommend that you add groups of users as defined in your authentication provider to the roles in Cognos 8 Planning, rather than individual users. This means that changes in group membership are reflected immediately in the roles without having to make changes in Cognos 8 To configure Analyst security: configure integrated Windows authentication if you want to execute macros without interaction specify a default library

50 Analyst

Chapter 4: Security assign access at object, library, or item level

Using the Contributor Administration Console set access rights for Contributor administrators to Contributor administration functions set rights for Contributor application users for Contributor applications

Configure Cognos 8 to Use an Authentication Provider

Cognos 8 components can run with two types of access: anonymous and authenticated. By default, anonymous access is enabled. To use Cognos 8 Planning, you must disable anonymous access so that users are required to log on. Only authenticated users can access your Cognos 8 Planning applications. For authenticated access, you must configure Cognos 8 components to use a namespace associated with an authentication provider used by your organization. You can also configure multiple namespaces. At run time, users can choose which namespace they want to use. Note: If you are using the Generate Transformer Model extension, you must add the Cognos Series 7 namespace. Local authentication export (LAE) files cannot be used.

Steps to Disable Anonymous Access

1. On each Content Manager computer, start Cognos Configuration. 2. In the Explorer window, under Security, Authentication, click Cognos. The Cognos resource represents the Cognos namespace. For more information, see the Administration and Security Guide. 3. In the Properties window, ensure that Allow Anonymous Access is set to False. 4. From the File menu, click Save.

Steps to Configure Authentication Providers

1. On each Content Manager computer, start Cognos Configuration. 2. In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace. 3. In the Name box, type a name for your authentication namespace. 4. In the Type list, click the appropriate namespace and then click OK. The new authentication provider resource appears in the Explorer window, under the Authentication component. 5. In the Properties window, for the Namespace ID property, specify a unique identifier for the namespace. 6. In the Properties window for Authentication, for the Allow session information to be shared between client applications, set the value to True.

User Guide 51

Chapter 4: Security This enables you to have single signon between multiple clients on the same computer. Note that you cannot have single signon between a Windows application, and a Web client application, for example, Contributor administration and Cognos 8. 7. Specify the values for all other required properties to ensure that Cognos 8 components can locate and use your existing authentication provider. 8. Test the connection to a new namespace. In the Explorer window, under Authentication, right-click the new authentication resource and click Test. 9. From the File menu, click Save. Cognos 8 loads, initializes, and configures the provider libraries for the namespace. For specific information about configuring each kind of authentication provider, see the Cognos 8 Planning Installation and Configuration Guide.

Add or Remove Members From Planning Rights Administrators and Planning Contributor Users Roles
Using Cognos Administration, add Contributor Administration Console administrators and Analyst administrators to the Planning Rights Administrators role. Add Contributor application and Analyst users to the Planning Contributor Users role.

Steps
1. In Cognos Connection, in the upper-right corner, click Cognos Administration. 2. On the Security tab, click Users, Groups, and Roles. 3. Click on the Cognos namespace. 4. In the Actions column, click the properties button for the Planning Rights Administrators or Planning Contributor Users role. 5. Click the Members tab. 6. To add members, click Add and do the following: To choose from listed entries, click the appropriate namespace. To search for entries, click the appropriate namespace and then click Search. In the Search string box, type the phrase you want to search for. For search options, click Edit. Find and click the entry you want. To type the name of entries you want to add, click Type and type the names of groups, roles, or users using the following format, where a semicolon (;) separates each entry: namespace/group_name;namespace/role_name;namespace/user_name; Here is an example: Cognos/Authors;LDAP/scarter;

52 Analyst

Chapter 4: Security 7. Click the right-arrow button, and when the entries you want appear in the Selected entries box, click OK. Tip: To remove entries from the Selected entries list, select them and click Remove. To select all entries in a list, click the check box in the upper-left corner of the list. To make the user entries visible, click Show users in the list. 8. Click OK. For more information, see the Cognos 8 Administration and Security Guide.

Enabling Planning Roles in Cognos 8

Planning tasks that require access to the Cognos 8 data store, such as running macros, go to production, and adding job servers, require additional security configuration. Access to the data store is restricted to certain groups through Cognos Administration. You must have a system administrator or a user from one of the following groups perform tasks that require the Cognos 8 data store. Optionally, you can add users to the required groups to perform the tasks.

Group
Data Manager Authors

Tool
Framework Manager

Task
Only members of the Data Manager Authors group can import from a Framework Manager data source. You must have a Data Manager Authors group member perform this task.

Directory Administrators

Cognos Administration You must have a Directory Administrator create Configuration, Data a data source named Cognos Planning Source Connections Contributor with a connection of type Cognos Planning - Contributor before performing go to production.

Report Administrators or Server Administrators

Cognos Administration A Report Administrators or Server Administrators Configuration, Content group member must publish and run macros in Administration Content Administration.

Restricting Access to the Everyone Group

The Everyone group represents all authenticated users and the Anonymous user account. The membership of this group is maintained by the product and cannot be viewed or altered. By default, the Everyone group belongs to several built-in groups and roles in the Cognos namespace. To restrict access, remove the Everyone group the System Administrators role and replace it with authorized groups, roles, or users. Optionally, remove the Everyone group from the Planning Contributor Users role to restrict access to Contributor plans. User Guide 53

Chapter 4: Security For more information about the Everyone group, and System Administrators role, see "Initial Security" in the Administration and Security Guide.

Recommendation - Creating Additional Roles or Groups for Contributor

To secure your Contributor applications, you may want to create roles or groups for the following users: Contributor client extensions Contributor work offline users for example, create one work offline role per Contributor application and assign the offline users to the relevant role. The application administrator must also belong to this role. system links translated applications

Planning Contributor User Roles

When you assign user rights to Contributor applications, the first time you click User, Group, Role in the Rights window, a list of all the Users, Groups, and Roles that are members of the Planning Contributor Users role is displayed. If the Planning Contributor Users role contains a large number of members directly below, you can improve performance by creating a smaller number of groups or roles below the Planning Contributor Users role to act as filters. Note: Members of roles can be users, groups, and other roles. Groups can contain users and other groups, but not roles.

Planning Rights Administrator Roles

If you have a large number of administrators, you may wish to create a roles, or groups for specific tasks, and then add the individual users to this role or group. For example, a role Allow System Links can be used for this task, and any user added to that role is assigned that right. For more information about creating groups or roles, see the Administration and Security Guide.

Configuring Access to Analyst

You must configure access to Analyst. Members of the Planning Rights Administrators group can set access rights at the library, object, or item level in Analyst. The type of access can be read, write, or control access. Usually users are allowed read, write, and control access rights for their own libraries, and read access to other libraries. However, you can change this to allow two or more users, groups, and roles, read and write access to the same objects, although not at the same time. The No Access setting is available only at the object level. It is used to override the library settings so that other users cannot view, read, write, or control specified objects.

54 Analyst

Chapter 4: Security Removing access rights at library level is achieved in a different manner. To remove access rights at library level, remove a user from the access list.

Filesys.ini Recommendations
We recommend using NT security on the filesys.ini file, and giving only the Planning Rights Administrators write access to the filesys.ini file. Every other user should have read rights.

Access Right Description

Read Access Read access allows objects to be viewed and copied but not changed. Read access is needed to view another user's data or to set up D-Links from another user's D-Cube. Read access allows a user to open other user's D-Cubes to view the data. Although changes can be entered, the data cannot be saved in the original D-Cube. If you try to save a D-Cube without write-access, you are not allowed to save the original but are prompted to save a copy with a new name. Write Access Write access allows a user to make changes to an object and save it. You can delete or rename the object. You can be given write access to another library. This allows you to open someone else's D-Cube, make changes, and save it. If you have write-access to a D-List, you can change formulas and formats and save it. The access is cumulative, so anyone with write access has all the privileges of read-access as well. Control Access Control access allows a user to set the security access in addition to having full read and write access. You can view, change, delete, rename, and set access to the object. If you have control access to a library, you can govern who can and who cannot access data in the library.

User Guide 55

Chapter 4: Security

Access Right Description

Default Access By default, libraries are set to read access for others and write access for your Settings own library. Objects that do not have an access setting of their own assume the access status of the library to which they belong. By default, objects have read-only access (the default setting for the library), but you can restrict this to no access if you want. Members of the Planning Rights Administrators group can set access to users, groups, or roles to determine who can and who cannot have access to objects. The access can be set at library level or object level. The type of access can be read, write, or control access. If access is given to a group, or role, users in that group or role inherit the maximum access rights available. To configure Analyst security, there are a number of steps you can take. Configure integrated Windows authentication if you want to execute macros without interaction, see (p. 56). Specify a default library, see (p. 57). Restrict D-Cube Access, see (p. 57). Assign access at the library level, see (p. 57). Assign access at the object level, see (p. 58). Assign access at the item level, see (p. 60).

Configure Integrated Windows Authentication

If you are going to run the Analyst Batch Scheduler wizard, you must configure integrated Windows authentication to secure jobs and macros in Analyst. To use Integrated Windows Authentication, you must use an authentication provider that supports it. All authentication providers supported by Cognos 8 can be configured to use Integrated Windows authentication, except for the SAP provider.

Steps
1. In Internet Information Services (IIS) Manager, right-click the Cognos8 virtual directory, and select Properties. 2. Click the Directory Security tab, and click Edit next to Enable anonymous access and edit the authentication methods for this resource. 3. Clear Anonymous access, and select Integrated Windows authentication. Click OK, and close IIS. 56 Analyst

Chapter 4: Security

Specify a Default Library

After you log on to Analyst, you must choose a default library. Otherwise, you are prompted to select from a list of available libraries based on your access rights, to use in the session.

Steps
1. Log on to Analyst. 2. Select a library from the list to use as a default library. 3. Click OK. Tips: To prevent you from being asked to select a library every time you open Analyst, from the Tools menu, click Options. Click the View tab, and select the Do not Prompt for default library check box, and click OK. You can select default libraries for Users, Groups, and Roles. From the File menu, select Administration, Maintain Libraries and Users. Click the name of the user, group, or role, and then click Properties. Select the default library.

Restrict D-Cube Access

You can select the Restricted D-Cube Access check box to prevent users from setting hold, lock, and protect patterns. The users will also be unable to remove the hold, lock, and protect patterns settings in D-Cubes.

Steps
1. In Analyst, from the File menu, click Administration, Maintain Libraries and Users. 2. Click the Users, Groups and Roles tab. 3. Select the users, groups, or roles that you want to restrict access to and click Properties. 4. Select the Restricted D-Cube Access check box. 5. Click OK.

Assign Access at the Library Level

Library level access is commonly used when a library contains confidential data such as salary information and expense accounts. Setting access rights at the library level means you allow or restrict access to a library for a user, group, or role.

Steps
1. In Analyst, from the File menu, select Administration, and click Maintain Libraries and Users.

User Guide 57

Chapter 4: Security The Table maintenance dialog box appears. 2. Click the library you want to set access rights for and click Properties. The Properties dialog box appears showing access rights for the library. 3. Click the Access tab, then click the name whose access you want to modify. 4. Click Read Access, Write Access, or Control Access. The name appears in the right-hand column with the appropriate access assigned. Tip: To remove access rights, click Remove. Note: Only names that have been added to Analyst are available, and by default, users have Control access over libraries they own. 5. Click OK. 6. In the Table Maintenance dialog box, click Close to return to Analyst.

Assigning Access at the Object Level

Security can be assigned to an object or group of objects. By default, no object-level security is specified, in which case objects inherit the security of the library to which they belong. The following table describes object -level access.

Access
Leave Blank No Access

Description
Objects inherit the library security settings Removes all access rights. You cannot view, read, write, or control objects. Can view and copy, but not change an object. Can change and save an object. It also confers full read-access. Can set security on an object. It also confers full read and write-access.

Read Access Write Access

Control Access

Set Access Rights at the Object Level

Security can be restricted for selected objects. If an object has access levels set at both the object and library level, the object assumes the more secure of the access levels. For example, if a D-Cube has read-only object-level security, but the library it belongs to has write-access, the D-Cube assumes read-only access, overriding the library security setting. However,

58 Analyst

Chapter 4: Security any attempt to give the D-Cube control access will be overruled by the write-access settings for the library. Access rights can be set or changed only if you have control access to the library and objects you are working on.

Steps
1. From the File menu, click Library, Objects. 2. Select the objects for which you want to set security. 3. Right-click anywhere in the list and choose Define Access. 4. Click Add to add a list of users who you want to give access to these objects. Only users, groups, and roles that have been added to Analyst are available. 5. Click the name of the user, group, or role. 6. Select the access level from the drop-down menu. 7. Click OK.

Set Read-Only Access to an Active Object

You can assign read-only access to the current active object.

Step
From the File menu, click Read Only Mode, Current Object.

[Read Only] appears in the title bar of the current object. Note: After you have switched to read-only mode, you cannot revert to write-mode without closing and re-opening the object.

Set Access Rights for a Library

Access rights for a library can be set up, changed, or removed for each user, group, or role. For each library, the type of access - Read, Write, or Control must be assigned to the user, group, or role. Access rights can be altered only by Planning Rights Administrators and users that have been given control-access.

Steps
1. From the File menu, click Administration, Maintain Libraries and Users. 2. In the Administration dialog box, click the Libraries tab and then double-click the library you want to change. 3. Click Access, and do one of the following:

User Guide 59

Chapter 4: Security If there are no users, groups, or roles listed, click Add, select the name in the Give Access to dialog box, select the access level and click OK. If users are already listed, click the user, and select the appropriate level of access from the Change Access to box. Note: Everyone is automatically a member of All Users, which by default has Read Access to all libraries. If you want to make a library secure, All Users access must be removed. Optionally, you can repeat this process to add access rights for other users. 4. After the access rights for users are set, click OK to return to the Users page and then click Close.

Set Read-Only Access Globally

You can assign read-only access to all objects globally so all objects are opened in read-only mode.

Step
From the File menu, click Read Only Mode, On/Off.

[Read-Only] appears in the program title bar.

Assigning Access at the Item Level

Security can be assigned to an item by using masks. A mask is used to hide individual items within a D-List or to prevent someone from writing over specified items. This is useful when you are on a network and want to allow limited access to large D-Cubes. You can be specific about the level of security applied to each item by applying an item named a mask. A mask contains a security pattern with a list of users and their access rights. It can be attached to one or more D-List items.

Managing Masks
You can customize the mask to give each user a key to unlock the restrictions. The choices are Read, Write, or Invisible. Items that are set to Read appear on the window but cannot be typed over or changed except by an indirect method such as a breakback. Items that are set to Write can be changed as usual. Items that are set to Invisible do not appear on the selection window. If a user has access at one level and a group to which the user belongs is restricted at a different level, the system takes on the highest access level of the two settings.

Example
If users have Invisible access but are members of All Users, which has Write access, they are able to see and change items because the program grants the highest level of access it can find. The only exception is that a user cannot have higher access to a D-List item than the object or library it belongs to. Anyone with the status of Planning Rights Administrator can override any security settings. If you are not on a network, it is typical for all standalone users to be Planning rights administrators, meaning they can access all models that are given to them. 60 Analyst

Chapter 4: Security Only users with Control access to a D-List can apply or remove a mask. It is possible to lock yourself out of certain items by attaching a mask that makes the items invisible. However, it is not as serious as it sounds because if you had control access to attach the mask, you also have the right to remove it. If you do not have Control access to a D-List, you cannot add or remove a mask. Usually, you only apply a mask to items from a single D-List within a D-Cube. In the unlikely event that item level security is applied to items from two D-Lists in the same D-Cube, there is a potential conflict of access rights at the intersection. In this case, the most secure of the two settings is applied. Thus, if you have Write access to UK and Read access to Sales, the UK Sales cell will give you Read access, the more secure of the two settings.

Create a Mask
Create a mask to hide individual items within a D-List or to prevent someone from writing over specified items. This is useful when you are on a network and want to allow limited access to large D-Cubes. When you open a D-Cube, items assigned to masks that are set to Invisible do not appear on the selection window. Items marked Read appear and can be changed temporarily but cannot be saved. If you have items that do not have full write-access in the current selection, you cannot save the D-Cube. This applies even if you have altered only items with Write access. Also, you cannot save the data in the D-Cube if a total can breakback over an item to which you do not have write access.

Steps
1. From the File menu, click Administration, Maintain Libraries and Users. 2. Click the Mask tab. 3. Click Add to create a new mask. 4. In the Name box, type a name for the mask. By default, a new mask has All Users defined as Invisible. This is the most secure setting possible and applying such a mask to a D-List item renders it invisible to everyone. 5. To customize the access levels for each individual or group to allow limited access: In the Create a new Mask dialog box, click Add and select the user and then click OK. 6. Change access to Read, Write, or Invisible. 7. Repeat for other users and groups until you have built up the required security pattern. If you are giving users write access at item level, ensure that they have write access at both object level and library level. Otherwise they cannot save the data. The default is for users to have read access to libraries unless they are given write access by the Planning Rights Administrator. If the selection opened has any items with read access, the whole D-Cube opens in read-only mode and you cannot save the D-Cube. To open with Write access, you must open a selection or slice of the D-Cube that has Write access. You can use Saved Selections to define Write or Read Only slices of the D-Cube. 8. Optionally, click Remove to withdraw the access privileges for a user or a group.

User Guide 61

Chapter 4: Security 9. Click OK to save the masks; then click Close to return to the main window.

Apply a Mask to Each D-List Item

Apply a mask to a D-List item to hide or protect items. A default mask can be set for a D-List. The default mask automatically applies to any items that are added after you set the default mask. If you want the default mask to apply to existing items, you must assign it to them when you set the default mask. Planning Rights Administrators can make a mask Public. This allows other users to use the same security pattern by attaching a public mask onto D-List items of their own. Changing a mask from public to not public makes the Planning Rights Administrator the new owner.

Steps
1. Open the D-List. If masks already are applied to a D-List, a small yellow padlock appears in the top left corner of the D-List. 2. From the D-List menu, click Options and then click the Security tab. 3. Click the item you want to mask, and then select a mask from the menu. 4. If you want to view or change the security pattern defined by a mask, click Edit Masks. 5. Optionally, you can right-click to get a menu allowing you to create a New mask, Edit or Clear an existing one, or Assign a mask to other items. 6. To assign a mask to other items, select a mask in the Multiple Assignment box and then click Assign. Select items that you want to apply the mask to and then click Move>>. 7. Click OK. Note: You can set a default mask that will apply to any new D-List items that are added later. 8. Click OK and save the D-List. To enter data in a D-Cube that contains masked D-Lists, from the File menu, click Open, D-Cubes, Edit Selection. Select only those items to which you have full write access. Do not select any sub total if you do not have write access to all the components of that subtotal. Items with Write access can be changed but only if the user also has write-access at object and library level.

62 Analyst

Chapter 5: Integration
Cognos Planning - Analyst can be used with other products. You can to take actuals from an Enterprise Resource Planning (ERP) system and combine them with planning information from Analyst and Contributor to perform comparative analysis using Cognos Performance Applications. The following diagram illustrates the various integration points between Cognos Planning and other Cognos products.

Published Data Real Time Data

Cognos 8 Business Intelligence

Cognos 8 Metrics Manager

Planning Cognos Connection

OLAP

Relational

Cognos 8 Business Intelligence Transformer 7.4

Cognos 8 Planning - Contributor

Cognos 8 Planning - Analyst

Performance Applications

Cognos 8 Controller

Cognos Finance

Financial Planning with Cognos Finance and Cognos Planning Products

This section describes what you need to know about using Cognos Finance with Cognos Planning. Cognos Finance, Cognos Planning - Analyst and Cognos Planning - Contributor create a highly complementary financial planning solution. Cognos Finance provides the consolidation, reporting, and schedule-based budgets. Analyst and Contributor provide planning, modeling, and driver-based

User Guide 63

Chapter 5: Integration forecasting and budgeting. Users can take historical actuals gathered in Cognos Finance and use them in Analyst and Contributor to forecast for the future. The Import From Cognos Finance wizard in Analyst facilitates the import of metadata and data from Cognos Finance into Analyst and the subsequent movement of data back and forth between the two applications.

Prerequisites and Required Components

To ensure seamless integration and effective use of Cognos Finance and Cognos Planning, you must: install both Cognos Finance and Cognos Planning in the same installation folder share a common authentication source (directory server namespace) have the Full Cognos Finance Client if using Network Installs. have at least one library in Analyst with control or write access.

Understanding the Process

Before you begin your planning exercise, you should understand the behavior of the new integration features and how they can be combined with existing features to represent the overall flow: The process starts in Cognos Finance with the creation of a Cognos Finance input form (LIF) or report (LRF). The Cognos Finance user defines the scope of the Planning problem and generates a report or input form representation, which contains the metadata and references to data. In Analyst, the Analyst modeler processes the Cognos Finance input form (LIF) or report (LRF) by using the Import From Cognos Finance wizard which: Generates the related D-Lists with an import link. Optionally, generates a D-Cube and D-Links to facilitate the data movement. Optionally, generates an e.List text file for later import into Contributor.

Once the modeling is completed in Analyst, the Contributor administrator: creates an application from the Analyst model. imports the e.List from the text file created in Analyst during the Import From Cognos Finance step. imports Cognos Finance data into Contributor using existing import mechanisms. The application goes to production and the plans are delivered and updated.

In Analyst, the modeler user defines a D-Link, using Contributor as a Source and Cognos Finance as the target to move the latest D-Cube data from Contributor to Cognos Finance. Financial reporting can then be done via the Cognos Finance Reporting Module.

64 Analyst

Chapter 5: Integration

Using Cognos Finance Input Forms or Report Files

Before you create your Input Form or Report in Cognos Finance, you need to understand how information is shared between Cognos Finance and Analyst. The following rules describe how the structural, financial, and formatting information in Cognos Finance is interpreted in Analyst. Analyst respects the switchable accounts options in the Cognos Finance report or input form, bringing data over as period activity or YTD. Note: All forms must have the Account dimension. The Import From Cognos Finance process respects the color attribute of the input form or report. Account dimension summaries are calculated accordingly to take account of Debit/ Credit formatting. The Import From Cognos Finance process automatically creates the summary total (sum of children) for each parent member in a hierarchical dimension (parent-child) relationship. If your input form or report includes a total but only some of the members that make up that total, the Import process brings in the subset of members and recalculates the summary total based on the subset. This may result in a different total from the parent total in Cognos Finance. The Import From Cognos Finance process recreates summary totals automatically (parent/child) . It does not transfer other non-aggregate formulas from Cognos Finance. You must recreate the formulas that apply in Analyst. Locked items and dimensions in Cognos Finance are not automatically locked in Analyst. Select the appropriate member for each filter dimension on the report or input form. The Import From Cognos Finance process honors this filter when creating D-Links. The filter dimensions will not appear in the Cognos Finance D-Cube created in Analyst. A new calculation status, External, is now available in Cognos Finance for accounts and components. It enables you to keep the values brought in from an external source for calculated and aggregated items of these dimension types. If the calculation status is not set to External, the value is changed the next time a Submission Calculation is done in Cognos Finance. For more information, see the Cognos Finance Application Administration Guide.

Importing From Cognos Finance

The Analyst modeler can import metadata and data from Cognos Finance using the Import From Cognos Finance wizard.

Steps
1. From the File menu in Analyst, click Import From Cognos Finance. This menu is only enabled if Planning and Cognos Finance are installed in the same installation folder. 2. Click the Cognos Finance system. 3. Click or type the location of the Cognos Finance report or input form. 4. Click a destination library to create the D-Lists, D-Links, and D-Cube. User Guide 65

Chapter 5: Integration 5. Click an item format. 6. Select the Define an e.List box if there is a future need to import e.List data into the Contributor Administration console. An e.List is a dimension with a hierarchical structure that typically reflects the structure of the organization. It determines how the application is distributed to end users. It can also be used to establish rules of security. The e.List data is typically imported into the Contributor Administration Console as a text file. Selecting the Define an e.List box causes an e.List specification page to be displayed. The specifications are used to automatically generate the necessary Contributor e.List import text file. 7. If you want to allow for the creation of a D-Cube, click Create a D-Cube. To create a D-Link that can be used to refresh a D-Cube from a Cognos Finance system, click Create a Cognos Finance to Analyst D-Link. To create a D-Link that can be used to update a Cognos Finance system, click Create an Analyst to Cognos Finance D-Link. When the D-Link name exceeds 31 characters, the D-Cube, the LRF and the LIF names are truncated to 31 characters. 8. Click the Cognos Finance dimensions that you want to create during import. The list of Cognos Finance dimensions is based on the definition of the LRF and LIF files selected in Cognos Finance. 9. If you are defining an e.List, click a dimension as an e.List. 10. If you are defining an e.List, click either Create D-List with all items or Create D-List with one item. If you choose Create D-List with one item, the first item is used. 11. If you are defining an e.List, type the location of the e.List import text file to be created. 12. When you define a D-Cube, select a filter, then double-click one or more items in the Source list to move the item to the Target list. When the options for creating a D-Link are selected and the target list contains existing D-Lists from Analyst, the D-Link mapping definition is partially created for the existing D-Lists. You must manually map the existing D-List to Cognos Finance dimensions to complete the mapping definition. 13. You can rename the D-Link, D-Cube, and D-List, which are created in Analyst. Click the object, press F2, and type the new name. 14. If you want to run the Cognos Finance to Analyst D-Link right away, click Run Cognos Finance to Analyst D-Link. If you do not click this option, an empty D-Cube is created. 15. Click Finish to proceed with import process. Once the process is completed, the newly created D-Cube is automatically opened you clicked Open D-Cube on Finish.

66 Analyst

Chapter 5: Integration

Financial Planning with Cognos Performance Applications and Analyst

You can use Cognos Planning and Cognos Performance Applications together to extract actuals from the data warehouse of an Enterprise Resource Planning (ERP) system and bring them into Cognos Planning, as structural data for the Analyst model and as the initial figures from the previous planning cycle for Contributor return completed planning data to the data warehouse using an ETL tool such as Data Manager for comparative analysis monitor live or published planning data during the planning cycle against current operational data in the Performance Applications warehouse

The data warehouse extracts, and changes that occur during the planning cycle, are managed using the Import from IQD wizard. Monitoring is done directly against Contributor data using the appropriate extensions. Steps Preparing Cognos Performance Applications Data for Planning In the Performance Application, identify the key performance indicators (KPIs) to plan by, monitor, and report on. Because planning is often performed at a different level from actuals, you may need to add to the dimensions from the data warehouse. Cognos consultants can help you in this identification and analysis. The Import from IQD wizard expects each dimension to have both an ID field and a description field, each of which must be unique across the dimension. Preparing for the Model in Analyst After the planning measures and dimensions that are available from Cognos Performance Applications have been identified, the Analyst user designs a model, and identifies any alternate data sources that are needed for the dimensions and measures. Because Performance Applications use multiple currencies for reporting, the Analyst user should determine what currency to use when data is published back into the Performance Applications warehouse. Note: If you create a D-List using the Import from IQD wizard, you should not add any items manually. If you do add items manually, these items will be removed every time you refresh the D-List. After planning models are designed and sourcing is identified, the solution to integrate the actuals information with planning information can be implemented using either the mapping table that is generated during the IQD import, or if the mapping tables are not required, you can use a Cognos package as a source to populate D-Lists in Analyst. Preparing e.Lists for Contributor Data As well as importing D-List data for the Analyst model, you can choose to generate e.Lists using data from IQD files, or if the data is modeled in Framework Manager and published as a package, you can also use Contributor Administration Links. User Guide 67

Chapter 5: Integration

IQD Files and the Import from IQD Wizard

The Import from IQD wizard in Cognos Planning works with any Cognos product that can generate Impromptu Query Definition (IQD) files, such as Impromptu and Framework Manager see "Generate Framework Manager Model Wizard" (p. 776). An Impromptu Query Definition is a transparent file that holds the SQL statement from which a hierarchy can be built. One IQD file is needed per dimension (D-List or e.List). The following diagram illustrates how the IQD wizard works in Cognos Planning and Performance Applications.
IQD Files

(2)

Analyst
Import from Impromptu Query Definition (IQD) Refresh from IQD Update from Data Warehouse D-Lists D-Cubes IQD SQL

(3)

e.List Text files

(4) (1)
PQD

Impromptu/ Framework Manager Contributor Application

Data Warehouse

(7) Performance Applications (or other data warehouses)

Contributor Publish Container

Cognos Planning

You can follow the workflow in the diagram from numbers 1 through 7 in sequence. 1. You model the data in Framework Manager or Impromptu that needs to be imported into Planning and save this as an IQD file. 2. Using the Analyst Import from IQD feature, browse to the IQD file and use the contents of the file to populate the various wizard steps. After the IQD file has been used once, it is not required by Analyst since Analyst stores the IQD details internally. The IQD file itself is only required if it is necessary to re-run the import wizard, as opposed to simply refreshing the D-List. Also as part of the import wizard, a mapping table is created that holds the relationship between the source business keys and the IDs generated by Planning. You can choose where this mapping table is stored, for example the source database. See Step 7 for more details. 3. When running the Import from IQD feature to create an e.List, the wizard generates the D-List in Analyst, either fully populated or with just a placeholder item, and also creates a text file that holds the e.List in the correct format for import into Contributor.

68 Analyst

Chapter 5: Integration 4. As part of the import wizard, you have the option to create a PQD (Planning Query Definition) file. This stores the import configuration for reuse. You can choose where this file is stored. The IQD file is not needed unless the import wizard needs to be re-run, and the essential elements of the IQD file, such as the SQL statement, are stored in the library folder in Analyst. 5. Since all the essential elements for the IQD import are stored in Analyst, after the initial import, all updates and refreshes are performed directly with the database. 6. Once the D-Lists in Analyst have been populated, the Contributor application is created/updated. As part of this step, the e.List file that was created as part of the import is imported into the Contributor Administration Console. Contributor end users enter their numbers into the created application. 7. When the Publish process in Contributor runs, the Planning IDs are output with the Planning data. To get the published data back into the source system, the published data is moved to the source system and the mapping table generated during the Import from IQD wizard is used to map Planning IDs to source business keys.

IQD File
The IQD file holds a definition of the data that will be imported into Cognos Planning, very similar to a SQL statement. You specify the order of the D-List or e.List items within the IQD, or the order of the underlying table or view is used by default. Alternative ordering can be applied manually to the generated D-List or e.List within Analyst, but this is lost if the D-List is updated again from the IQD. The wizard imports from flattened hierarchy structures only. Ragged hierarchies are not supported. In a flattened hierarchy, all level items have the same number of parent levels. In a parent-child (ragged) hierarchy, not all level items are at the same hierarchy level.) To import a ragged hierarchy, use the standard Analyst D-List import. The Import from IQD wizard expects each level to have an ID field as well as a description field, which must both be unique across the dimension. All settings are retained in PQDs (Planning Query Definitions) after the initial configuration. You can use PQDs to speed up the repeated import of the same IQD file. If you use the PQD to import another IQD file, ensure they both generate similar result columns.

Mapping Table
The Import from IQD wizard generates a mapping table in a database selected by the user to map the IDs of the data warehouse table to the Planning IDs. This is necessary so that Planning data can be returned to the Performance Applications data warehouse even if the warehouse has changed. Use this table to map the published data from Contributor into the source database (or other database that has the same source dimension data). You can specify an alternative target database for the mapping table, as long as the database connection and user details are configured in Cognos Connection or Framework Manager.

User Guide 69

Chapter 5: Integration

Connections and Security

The Import from IQD wizard uses any connection that has been set up in Cognos Connection or Framework Manager. If a connection that requires a client installation, such as Oracle, DB2 or ODBC, is used when setting up a database connection for the IQD, the appropriate client configuration must also exist on the machine where the IQD import will be executed. This is a limitation of such connections. Configure the security to the chosen data source in Cognos Connection or Framework Manager. When the wizard is run, it checks to confirm that you have access to the data source used in the IQD. If the data source connection does not exist in Cognos Connection for Framework Manager, the wizard will stop the process and display a message stating that security details must be configured before the wizard can proceed. You can tell whether a D-List is sourced from an IQD file by opening the D-List, and checking to see if the Refresh option is disabled, which indicates the D-List is not sourced from an IQD file.

Standard D-Lists
For standard D-Lists, specify the leaf-level of the hierarchy (Item Name), and the leaf-level business ID and the table-unique identifier (Dimension ID) the other fields from the SQL statement in the IQD file that are to be used as levels how to configure the relationship between levels, starting from the top level Any additional, non-hierarchy fields that are required in the mapping table, such as background information about products or customers for additional reporting, are added as pass through fields. A Pass-Through field is one that appears in the Mapping table but not in Analyst or Contributor.

Time D-Lists
For time D-Lists, specify the same hierarchical information as a standard D-List. In addition, select the date format, and the period start and end date fields that will be used in Analyst to define the 'from' and 'to' columns for the timescale options of the D-List.

e.Lists
For e.Lists, specify the file path for each e.List file that will be generated by the process. Also, specify whether the entire e.List should be imported into Analyst or just a single item. Regardless of choice, the entire e.List is created in the e.List file that should be imported in Contributor via the Administration Console. Remember the D-List generated in Analyst is only the placeholder D-List that represents the e.List in Contributor. There are scenarios where it makes sense to have the entire e.List in Analyst, but often the e.List is too large to hold in Analyst, so only a single placeholder item is required in Analyst. After this step, the same hierarchical information will be specified that is applicable to the standard D-List. The e.List file that is generated will contain IDs that match those in the mapping table.

70 Analyst

Chapter 5: Integration

Managing Changes from the Data Warehouse

There may be changes to the data warehouse during the Planning cycle. If no items have been added manually to the Analyst D-List, use the Import from IQD wizard to manage updates, inserts, and deletes of the D-List or e.List items automatically. Refreshing from the IQD overwrites any manual changes you have made so you cannot manage updates, inserts, and deletes outside of the IQD. You can use the Import from IQD wizard to update any D-List created by the wizard in previous releases. Note: If you add items to the D-List manually in Analyst, they are removed when you refresh the D-List from the warehouse. If you run the Import from IQD wizard, you can monitor changes. If you use a macro, you do not receive any warnings. For all existing D-Lists, if a new ID field is not unique, or if the truncated description field (the first 50 characters) is not unique, the import from IQD process stops and the D-List is returned to its original state before the process began. In the wizard, you can choose to generate new IDs for all D-List items. This refreshes the entire dimension, including the IID, GUIDs, and mapping table, however changing internal IDs could lead to a loss of data in Contributor.

Update
If only the level description changes (not the field marked as ID) then the dimension is updated and retains the original IDs and mappings. The rest of the dimension remains untouched. Any pass-through columns should also be updated in the mapping table in the source database, even if no change has occurred within the D-List or e.List. The position of the items within the hierarchy should also be retained or updated as appropriate. If an item moves from one position to another within the hierarchy, then all item IDs should remain the same.

Insert
If a new item appears in the source table, or an existing item is given a new ID, then it is inserted as a new item into the D-List or e.List in the same position as it is found in the IQD SQL statement (according to the IQD ordering or according to the SQL table order). The other items of the dimension remain untouched. The mapping table is updated with the new item, but the existing mapping details remain untouched.

Delete
If an item is removed from the source table, then it is removed from the D-List or e.List and marked as deleted in the mapping table, although the entry still remains in the mapping table. The other items remain untouched.

Deployment Options for IQD

You can move the IQD-sourced D-Lists between different environments, like Development, Test, Production.

User Guide 71

Chapter 5: Integration

Unchanged IQD Setup

If the IQDs that have been set up in Development do not need to be changed in the other environments, for example if the SQL statement in the IQD is correct regardless of environment, then you can move the Analyst libraries through the environment like normal. You do not need to the move the IQD file itself because the import definition is stored in the Analyst library after the initial run-through of the IQD wizard. The only things you need to create in the target environment are: The appropriate database connections. Depending on how you have configured the IQD import, you will need connections for the source and mapping table databases (which could be the same). The names of the connections should be the same in the target environment as in the source environment. The mapping table will need to be moved to the target environment. If the mapping table cannot be found, the update will fail.

Changed IQD Setup

If the IQDs need to be updated in the target environment, for example to change the SQL statement, then these too will need to be moved to the target environment. For each D-List that relies on an IQD file that needs to be updated, do the following: Edit or recreate the IQD file to incorporate the changes. If the file path to the IQD is not the same as in the previous environment, you will receive a warning and then be able to browse to the new location. Run the IQD Wizard and run the PQD file. This will step through the wizard with the settings that were used for the original configuration. This will also read the IQD file into Analyst again, so any changes you have made will be picked up. If you have made changes like adding a WHERE clause to the SQL statement in the IQD file, then no alterations to the settings will be required. If you have removed fields from the SQL statement that were previously used in the IQD Wizard, or have added fields that need to be incorporated, you can add them at the appropriate wizard step. At the end of the wizard, click Overwrite Existing D-List and also Keep IDs for Matching D-List Items so that the existing D-List is correctly updated. After this process runs, the settings are incorporated into Analyst and you no longer need the IQD files.

Creating Planning Models and Data from Cognos Performance Applications Data
When you create planning models from Performance Application data, you use: the Cognos Performance Applications data warehouse, to supply data for the planning model and the initial values in Contributor As for any data source, the connection information to the Cognos Performance Applications data warehouse must be in Cognos Connection or Framework Manager. Ensure that the Cognos Performance Applications data warehouse is prepared with actuals. 72 Analyst

Chapter 5: Integration For information about dimensions available, see the Report Administration Guide for your Performance Application. Impromptu or Framework Manager, to generate the IQDs, or if IQDs are not needed for mapping tables, then you can publish models as a package Analyst, to create the planning model Contributor, to publish the model, the initial values, and to collect the planning data Contributor Administration Links to import data that is modeled in Framework Manager and published as a package Cognos Data Manager, to move the data between the Contributor and Performance Applications databases,

To create a Planning application from a Performance Application, do the following: Determine the granularity of the plan (p. 74). Create D-Lists in Analyst from IQD files. Create a placeholder e.List in Analyst from an IQD file. Create D-Cubes in Analyst from D-Lists. Create an application in Contributor by importing the planning models created in Analyst. Populate the e.List that was creating in Analyst as a placeholder. Assign user access rights to each e.List item. User rights to the data in the D-Cube are established using an e.List. An e.List is the D-List that represents the business area responsible for providing the planning information. Populate Contributor application D-Cubes with actuals from the Cognos Performance Applications as seeding plan values. Make Contributor models available to planning users. In the Contributor Administration Console, the administrator runs the Go to Production process and sets up the Contributor Web site so that the planning models become available to all participating planning users. Users can review plans and enter data using their distributed Web browser environment. Publish planning data back to Cognos Performance Applications' data warehouses.

After user input and modifications, the planning data can be published back to the data warehouse where the planning data and actuals can be compared and analyzed. The Contributor administrator performs a Publish from Contributor which exports the D-Lists and the fact data to database tables. From the Publish tables, the administrator needs to ETL (Extract-Transform-Load) the data into the Performance Applications database, using the mapping table generated by the IQD to match Contributor IDs with Business Codes. For more information about publishing planning data, see "Publish Planning Data " (p. 79).

User Guide 73

Chapter 5: Integration

Monitoring Planning Activity using Business Intelligence (BI) and Cognos Metrics Manager
Live and published planning data can be compared with actuals using Cognos PowerPlay cubes, Cognos Impromptu catalogs and reports, Cognos Metrics Manager and Cognos Framework Manager models for reporting as appropriate. All these can be done using Contributor extensions.

Determine Plan Granularity

You must ensure that Cognos Performance Applications has been set up to support planning before creating a planning model in Cognos Planning. Steps Determine the granularity of the plans that will be created in Cognos Planning. Assess the business requirements to determine the planning measures and the dimensional context for the measures before creating the extract queries. The dimensional context identifies the D-List candidates critical to the measures. The dimensions you create should have some relation to the measures. Also, ensure that the measures and dimensional relationships exist in the Cognos Performance Application. You must determine which dimension will control the access to the data (the e.List). Understand the planning requirements and develop an initial draft of the planning model. The time you spend drafting the model will greatly reduce the need to make changes later, of a kind that could affect the effort required to publish data and generate plan data to the warehouse. Determine the level of data that is required for planning, and compare that against the data that is available. Using this information, create and customize the dimension structure to define the business model.

Create a Planning Model in Analyst

D-List information is brought from dimensions in Cognos Performance Applications into Analyst using the Import from Impromptu Query Definition (IQD) wizard.

Mandatory IQD (Impromptu Query Definition) Columns

The following identifies the mandatory columns that must exist in the IQD in order for the D-List/ Planning dimension process to be successful. For normal D-Lists the IQD has the following mandatory columns: Dimension ID. The Dimension ID is reserved for other Cognos reporting tools. It should take the values of item code. Item Code (ID field). This column is the reference key in the source database. Item codes and descriptions must be unique across all imported levels.

74 Analyst

Chapter 5: Integration Item Name (description field). All item names inside a D-List must be unique and is limited to 50 characters. Input item names that are longer than 50 characters are automatically truncated during the D-List creation.

For date based or time scale D-Lists, the IQD must have the following additional mandatory columns: Period start date Period end date

To create a D-List, either a brand new D-List is created or an existing one gets replaced. There are two options for replacing an existing D-List: Replace the existing D-List and retain the existing, corresponding item IDs. This option preserves the data in the D-Cubes that use the D-List. All other attributes of the D-List are replaced. Use this option when it is necessary to track historical changes to cube data. Replace the existing D-List and preserve only the D-List name. All item IDs are new. Even items with the same name receive new IDs.

Both options replace all D-List items. Any new items added to the D-List using Analyst is be lost.

Steps
1. From the File menu, click Import from, Impromptu Query Definition (IQD). 2. Select the type of D-List to create. You can choose to create a normal D-List, a time scale D-List, or an e.List. You can also use PQD files that are saved IQD imports. These files contain all the settings for IQD imports that you might have run previously and are designed to minimize configuration for similar D-Lists. 3. Select the mandatory IQD columns to import. For information about mandatory IQD columns, see "Mandatory IQD (Impromptu Query Definition) Columns" (p. 74). 4. For time scale D-Lists only, select the start date and end date. 5. Optionally, define the D-List hierarchies. 6. Optionally, preview the data source records. 7. Name the D-List and select a library with which to associate it. 8. Select the target for the mapping table. This target database will need to be configured in Cognos Connection/Framework Manager. After you run the wizard, the import process creates a mapping table for each D-List in a user selected database. The mapping tables contain the following critical reference information for the Analyst Planning model and the data source. Reference information for the Analyst item IDs, which are unique for each item. Reference information for the data source Item code, which is also unique for each item.

User Guide 75

Chapter 5: Integration When importing initial values to a D-Cube later, the GUID and item code from the planning dimension tables should be used to build correct insert values. Repeat this process to create all D-Lists required for one or more D-Cubes.

Create an e.List for the Contributor Application

A Contributor application is created from D-Cubes selected from an existing Analyst model. Each D-Cube must have an e.List dimension. An e.List is created in Analyst as a placeholder D-List. This e.List can either be created with one item or with all items. If created with one item only, this item acts as a place holder with one root item. If created with all items, the e.List is created in Analyst with all items. The complete e.List hierarchy and item IDs are saved to a text file that Contributor will use to populate the complete e.List. Note: If you create the e.List with all the items in Analyst, you may run the risk of having a large Analyst model because the whole Contributor model would effectively be in Analyst.

Create D-Cubes
A D-Cube in Analyst is made up of two or more D-Lists. To create a D-Cube based on Cognos Performance Applications, all D-Lists can be created from IQD files.

Set up a Contributor Application

Once the model has been created in Analyst, in the Contributor Administration Console, the administrator creates the Contributor application, grants access to users and imports data. Steps The administrator creates a new application, selecting the library containing the model, and selecting the D-List to use as the e.List. Populates the e.List by importing the text file created earlier. Sets up access to the application through the e.List, users and rights, and through access tables. Configures application settings by defining one application data store and two publish data stores. Imports data into D-Cubes as initial planning values or seeding values. These values are normally from the actuals of the Performance Applications data warehouse. Dimensions in Cognos Performance Applications are often at a lower level of granularity than is required for planning purposes so values will typically be generated from summarizations or aggregations. Runs the Go to Production process to put the application into production state. Sets up the Contributor Web site to make the production application available to planning (contributing) users.

76 Analyst

Chapter 5: Integration

Populate the Planning Application in Contributor

You can import data that has been modeled in Framework Manager and published as a package into Contributor using Administration Links. You can also import historical actual measures from Cognos Performance Applications into Cognos Planning D-Cubes in the format of: Item name of dimension (D-List) 1 Item name of dimension (D-List) 2 Item name of dimension (D-List)... Item name of dimension (D-List) n Measure value

The item names are those seen in Planning. They may not be the same as produced by the original IQD, due to manual modifications after the D-List creation or truncations during the D-List creation. The planning dimension tables must be used to retrieve correct item names used for the value import. The most efficient way to import data into Cognos Planning is through Contributor. This can be done using SQL or Data Manager. The decision whether to use SQL or Data Manager depends on the complexity of the import and your expertise with SQL and Data Manager. If the data is modeled in Framework Manager and published as a package, you can also use Contributor Administration Links. The processes to import the data are: Using SQL for Loads A simple SQL query can be used to load directly from the Cognos Performance Applications into the Contributor import IM table. Execute the Build and Validate the AAA_ Table Data Data Manager is unable to deliver data directly to the IM_ table so this step loads the IM_table from the AAA_table using an INSERT statement. Notes In a multi-measure planning cube, match the Measures D-List column to the Measures Column in the Import Table. If re-loading, TRUNCATE the table first. TRUNCATE TABLE <table_name>, where the <table_name> is table that all rows are to be removed. This is a SQL command in Oracle and SQL Server. There is an option in Contributor Import, Zero Data, which accomplishes the same thing. Zero Data should only be used if intending to replace the target D-Cube's data entirely with the data set being imported. Import the data into Contributor To import the data into the Contributor Production environment, the Go to Production process must be completed.

User Guide 77

Chapter 5: Integration Assign access for the published table Assign synonyms and grants for published table to user schema (Oracle) and assign permissions and access rights for user (SQL Server). Using an appropriate SQL tool: Login to the Contributor data store that is linked by the Contributor application's data store. Build planning views for reporting on published tables with Cognos Performance Applications fact. Build reports on planning views.

Access to Published Cognos Planning - Contributor Tables

In order to access the data in published Contributor tables, you must assign: synonyms and grants for a published table to a user schema (Oracle) permissions and access rights for user (SQL Server)

Steps
1. Using an appropriate SQL tool, log in to the Cognos Planning - Contributor application's data store. Note: The DBA must assign the appropriate login security and privileges. For example in Oracle:
GRANT CONNECT TO <Planning Contributor account>;

2. Grant access to the published tables so that the Cognos Performance Applications account can select the data. For example in Oracle:
CREATE SYNONYM ET_REVENUE_AND_EXP FOR <Planning Contributor account>.ET_REVENUE_AND_EXP; GRANT SELECT ON <Planning Contributor account>..ET_REVENUE_AND_EXP TO <Performance Applications account>;

Tip: The following Oracle script can be used to generate the above scripts:
select 'CREATE SYNONYM ' || TABLE_NAME || ' FOR <Planning Contributor account>.' || TABLE_NAME || ';' from ALL_TABLES WHERE OWNER = '<Planning Contributor account>' AND (TABLE_NAME LIKE 'HY_%' OR TABLE_NAME LIKE 'ET_%') select 'GRANT SELECT ON <Planning Contributor account>.' || TABLE_NAME || ' TO <Performance Applications account>;' from ALL_TABLES WHERE OWNER = '<Planning Contributor account>' AND (TABLE_NAME LIKE 'HY_%' OR TABLE_NAME LIKE 'ET_%')

78 Analyst

Chapter 5: Integration

Publish Planning Data

Users can carry out a plan and actuals comparison, after the required planning is complete and the actuals for the same period are captured. To do this, the plans need to be extracted and compared with the actuals from Cognos Performance Applications.

Publish Layouts
You can choose from these types of publish layouts: table-only, incremental, and view. The table-only layout gives users greater flexibility in reporting on Planning data. The table-only layout can also be used as a data source for other applications. This layout is required by the Generate Framework Manager Model Admin extension and the Generate Transformer Model Admin extension. The incremental publish layout publishes only the e.List items that contain changed data. Users can schedule an incremental publish using a macro or through Cognos Connection and Event Studio. You can achieve near real-time publishing by closely scheduling incremental publishes. The view layout generates views in addition to the export tables. This layout is for historical purposes.

The following types of tables are created when you publish using the table-only layout and the incremental publish layout.

Table type
Items Hierarchy

Description
Describes the D-List items.

Prefix or name
it_

Contains the hierarchy sy_ for the simple hierarchy cy_ information derived from the for the calculated hierarchy. D-list, which is published to two associated tables. Contains published D-Cube data. et_ Contains annotations, if the an_ for cell and audit annotations option to publish annotations is annotationobject for tab (cube) selected. and model annotations Contains metadata about the publish tables. P_APPLICATIONCOLUMN P_APPCOLUMNTYPE P_APPOBJECTTYPE P_APPLICATIONOBJECT

Export Annotation

Metadata

Common

Contains tables used to track when major events occurred in the publish container.

adminevent adminhistory containeroption

User Guide 79

Chapter 5: Integration

Table type
Job

Description

Prefix or name

Contains tables with information job jobitem jobitemstatetype relating to jobs. jobstatetype jobtask jobtype A table used to lock objects in the P_OBJECTLOCK system when they are being processed. publishparameter Publish information about files attached to the Contributor application. ad_cube

Object locking

Publish parameter Attached document

The following types of tables are created when you publish using the view layout.The Contributor administrator publishes from Contributor which exports the D-Lists and the fact data to database tables. Contributor publishes the planning data into a set of tables with standard prefixes.

View Layout Contributor Standard Prefixes Planning Data

an av et ev fv hy it Annotation (for D-Cubes) Annotation view Export/publish (for D-Cubes) Export view Fact view Hierarchy (for D-Lists) Item (in D-Lists)

In order to perform the actuals vs. plan comparison, this data must be made available in such a manner that the Business Intelligence tools can access. The problems are: Planning data is linked to the D-Lists via GUIDs, whereas Performance Applications actuals data is linked via item code of dimensions. The planning dimension tables provide lookup links. Physically, the Planning data may be stored in a different database (or schema in Oracle) than the Performance Applications data and thus with different default security on the tables.

80 Analyst

Chapter 5: Integration In order to accomplish this, views can be created in the Planning database to expose the Planning data as well as provide access via grants.

Automation
You can automate the update of a D-List or recreation of an e.List file using either of these Analyst macros: @DListItemImportIQD (p. 645) @RefreshDataWarehouse (p. 649)

Manual updates to D-Lists and e.Lists will be removed without messages if you update lists using macros.

Command Line
The re-use functionality can be executed using these command line options: Update D-List from IQD Update IQD Mapping Table Upgrade D-List created from an earlier release

Update D-List from IQD

This command line updates a D-List from its IQD source. Any changes done manually in Analyst will be lost. Item names, hierarchies and display orders are synchronized with the IQD source. D-Lists created prior to this release are upgraded before running this command line.

Update IQD Mapping Table

This command line synchronizes the mapping table with the Analyst D-List. It is provided for backward compatibility only, where a D-List can be changed manually (not recommended practice) . D-Lists created prior to this release are upgraded before running this command line.

Upgrade D-List created from an Earlier Release

This command line upgrades a D-List created from a previous release.

User Guide 81

Chapter 5: Integration

82 Analyst

Chapter 6: Importing Data from Cognos 8 Data Sources

You can import data into Cognos 8 Planning - Analyst and Cognos 8 Planning - Contributor from any data source that can be published as a Cognos 8 package. For more information about supported data sources, visit the Cognos Global Customer Services Web site (http://support.cognos.com). There are additional considerations when importing SAP BW data into Cognos 8 Planning. For more information, see "Working with SAP BW Data" (p. 88). For information on Cognos 8 Planning configuration requirements for SAP BW, see the Cognos 8 Planning - Installation and Configuration Guide. You must have Framework Manager installed. If you are working with SAP BW data, you must install the SAP gateway functions. For more information, see the Cognos 8 Planning - Installation and Configuration Guide. Importing data from Cognos 8 data sources involves the following tasks. In Cognos Connection, create a data source connection (p. 84). In Framework Manager, create a new project and import the metadata into the project (p. 86). In Framework Manager, model the source. See the Framework Manager User Guide for more information. Create and publish the Cognos package to Cognos Connection (p. 87). If importing into a Contributor application, in the Contributor Administration Console, create and run an administration link. Tip: You can create and schedule macros that run administration links. If importing into an Analyst model, choose one of the following options: Select a Cognos package as a source in a D-List Import. Select a Cognos package as a source in a D-Link. Select a Cognos package as a source in an A-Table, or import a Cognos package as a Source in an A-Table.

You can also automate the import of Cognos packages using the @DListItemImportCognosPackage macro.

User Guide 83

Chapter 6: Importing Data from Cognos 8 Data Sources

Create a Data Source Connection

When you create a data source, you must provide the information required to connect to the database. This information is provided in the form of a connection string. You can include authentication information for the database in the data source connection by creating a signon. Users need not enter database authentication information each time the connection is used because the authentication information is encrypted and stored on the server. The signon produced when you create a data source is available to the Everyone group. Later, you can modify who can use the signon or create more signons.

New Data Sources

You can create data sources in the portal or in Framework Manager. Because they are stored on the server, data sources appear in both places, regardless of where they were created. Existing data source connections can be edited only in the portal. If you are an administrator, you can set up all required data sources before models are created in Framework Manager so that all connections are available in the Framework Manager Import wizard. Data sources are stored in the Cognos namespace and must have unique names. For example, you cannot use the same name for a data source and a group.

Physical Connections
A data source defines the physical connection to a database. A data source connection specifies the parameters needed to connect to a database, such as the location of the database and the timeout duration. Note: The schema name in the connection string for an Oracle database is case-sensitive. If the schema name is typed incorrectly, you cannot run queries.

Required permissions
Before creating data sources, you must have write permissions to the folder where you want to save the data source and to the Cognos namespace. You must also have execute permissions for the Data Source Connections secured feature.

Steps to Create a Connection

1. Open Cognos Connection. 2. In the upper-right corner, click Launch, Cognos Administration. 3. On the Configuration tab, click Data Source Connections. 4. Click the New Data Source button. 5. In the name and description page, type a unique name for the connection and, if you want, a description and screen tip, and then click Next.

84 Analyst

Chapter 6: Importing Data from Cognos 8 Data Sources 6. In the connection page, click the type of database to which you want to connect, select an isolation level, and then click Next. Note: For SAP BW data sources, the isolation level is read-only. Note: For Cognos Planning - Contributor 7.3 data sources, select Cognos Planning - Series 7. For Cognos 8 Planning - Contributor data sources, select Cognos Planning - Contributor. The connection string page for the selected database appears. 7. Enter any parameters that make up the connection string, and specify any other settings, such as a signon or a timeout. One of the following options may apply depending on the data source to which you are connecting: If you are connecting to a Cognos cube, you must enter the full path and file name for the cube. An example for a local cube is C:\cubes\Great Outdoors Company.mdc. An example for a cube on your network is \\servername\cubes\Great Outdoors Company.mdc. If you are connecting to a password protected PowerCube, click Cube Password, and then type the password in the Password and Confirm Password boxes. If you are connecting to an ODBC data source, the connection string is generated from the name you enter in the ODBC data source box and any signon information. The data source name is an ODBC DSN that has already been set up. You can include additional connection string parameters in the ODBC connect string box. These parameters are appended to the generated connection string. If you are connecting to a Microsoft Analysis Services data source, select an option in the Language box. If you selected Microsoft Analysis Services 2005 you must specify an instance name in the Named instance since you can have more than one instance on each server. If you use a Microsoft Active Directory namespace and you want to support single signon with Microsoft SQL Server or Microsoft Analysis Server, select An External Namespace, and select the Active Directory namespace. For more information about configuring an Active Directory namespace, see the Cognos 8 Planning Installation and Configuration Guide. If you selected Microsoft Analysis Services 2005, you must specify an instance name in the Named instance since you can have more than one instance on each server. If you selected Cognos Planning - Series 7, you must specify the Planning Administration Domain ID and the namespace. If you selected Other Type as the data source type, you must build the connection string manually.

Tip: To test whether parameters are correct, click Test. If prompted, type a user ID and password or select a signon, and then click OK. If you are testing an ODBC connection to a User DSN, you must be logged on as the creator of the DSN for the test to succeed. 8. Click Finish.

User Guide 85

Chapter 6: Importing Data from Cognos 8 Data Sources The data source appears in Data Source Connections on the Configuration tab, and can be selected when using the Import wizard in Framework Manager.

Create a Framework Manager Project and Import Metadata

A project is a set of models, packages, and related information for maintaining and sharing model information.

Steps
1. From the Windows Start menu, click Programs, Cognos 8, Framework Manager. 2. In the Framework Manager Welcome page, click Create a new project, and specify a name and location. You can add the new project to a source control repository, see the Framework Manager Help for more information. 3. In the Select Language page, click the design language for the project. You cannot change the language after you click OK, but you can add other languages. Note: If an SAP BW server does not support the selected language, it uses the content locale mapping in Cognos Configuration. If a mapping is not defined, Framework Manager uses the default language of the SAP BW server. 4. In the metadata source page, select Data Sources. 5. Select a data source connection and click Next. If the data source connection you want is not listed, you must first create it (p. 84). 6. Select the check boxes for the tables and query subjects you want to import. Tip: For usability, create a package that exposes only what is required. 7. Specify how the import should handle duplicate object names. Choose either to import and create a unique name, or not to import. If you choose to create a unique name, the imported object appears with a number. For example, you see QuerySubject and QuerySubject1 in your project. 8. If you want to import system objects, select the Show System Objects check box, and then select the system objects that you want to import. 9. Specify the criteria to use to create relationships and click Import. For more information, see the Framework Manager User Guide. 10. Click Next and then Finish. Note: You save the project file (.cpf) and all related XML files in a single folder. When you save a project with a different name or format, ensure that you save the project in a separate folder.

86 Analyst

Chapter 6: Importing Data from Cognos 8 Data Sources

Create and Publish the Cognos Package

You create and publish a package to make the data available to Cognos 8 Planning.

Steps to Create a Package

1. Click the Packages folder, and from the Actions menu, click Create, Package. 2. In the Provide Name page, type the name for the package and, if you want, a description and screen tip, and click Next. 3. Specify whether you are including objects from existing packages or from the project and then specify which objects you want to include. 4. Choose whether to use the default access permissions for the package: To accept the default access permissions, click Finish. To set the access permissions, click Next, specify who has access to the package, and click Next. You can add users, groups, or roles. See the Framework Manager User Guide for more information. 5. Move the language to be included in the package to the Selected Languages box, and click Next. 6. Move the sets of data source functions you want available in the package to the Selected function sets box. If the function set for your data source vendor is not available, make sure that it was added to the project. 7. Click Finish and choose whether to publish the package.

Steps to Publish a Package

1. Select the package you want to publish. 2. From the Actions menu, click Package, Publish Packages. 3. Choose where to publish the package: To publish the package to the report server, click Cognos 8 Content Store. Click Public Folders to publish the package to the public folder. You can create folders in the public folder also. Click My Folders to create your own folder and publish the package to it. To publish the package to a network location, click Location on the network.

4. To enable model versioning when publishing to the Cognos 8 Content Store, select the Enable model versioning check box and type the number of model versions of the package to retain. Tip: To delete all but the most recently published version on the server, select the Delete all previous model versions check box.

User Guide 87

Chapter 6: Importing Data from Cognos 8 Data Sources 5. If you want to externalize query subjects, select the Generate the files for externalized query subjects check box. 6. By default, the package is verified for errors before it is published. If you do not want to verify your model prior to publishing, clear the Verify the package before publishing check box. 7. Click Publish. If you chose to externalize query subjects, Framework Manager lists which files were created. 8. Click Finish.

Working with SAP BW Data

The SAP BW model is an OLAP source and is optimized for reporting rather than for high volume access that is sometimes required for planning activities. To efficiently access data for Cognos 8 Planning, create a detailed fact query subject that will access fact data at a detail level suitable for use with Cognos 8 Planning. Tip: If you have OpenHub, you can use it to generate a text file or database table from SAP BW. You can then manually create a Framework Manager model and Cognos Package from the tables and then import the package into Planning using an Administration Link, D-Link, or D-List import. For Cognos products to be able to access SAP BW as a data source, the user accounts used to connect to SAP must have specific permissions. These permissions are required for the OLAP interface to SAP BW and are therefore relevant to both reporting and planning activities. For more information about guidelines for working with SAP BW data, see the Framework Manager user Guide. For more information about access permissions for modelling and reporting access, see the Cognos 8 Planning Installation and Configuration Guide. For information about setting up your environment to work with SAP BW and Planning, see the Cognos 8 Planning Installation and Configuration Guide.

Create a Detailed Fact Query Subject

The detailed fact query subject is a model query subject based on database query subjects and calculations. The relational folder is where the SAP star schema is imported to. The detailed fact query subject is the logical representation of the fact table and the query subjects in the relational folder are the physical representation of the SAP fact table. We recommend that you do not modify the contents of the relational folder, unless advised by customer support.

Steps
1. In Framework Manager, click the Key Figures dimension. 2. From the Tools menu, click Create Detailed Fact Query Subject. 3. In the metadata wizard, select the data source you want to use.

88 Analyst

Chapter 6: Importing Data from Cognos 8 Data Sources You can create a new data source by clicking the New button and specifying SAP BW for Planning as the type. 4. Click OK. Framework Manager creates a model query subject named Detailed_Key_Figures and a separate folder containing references to the relational objects. The references to the relational objects are the physical layer. 5. Create the package. Note: Packages that contain the Detailed_Key_Figures query subject are only accessible or supported for the report authoring tools, such as Query Studio and Report Studio if they are hidden by doing the following: In the Define Objects screen click the down arrow and choose Hide Component and Children. Click Detailed_Key_Figures and Relational_Objects.

6. Publish the package.

Recommendation - Query Items

It is a common requirement to concatenate two or more fields from a data source when creating D-Lists in Analyst. When importing D-Lists from a Cognos Package, you perform the concatenation in Framework Manager by creating a new query item. The query item can then be included in the published package and imported into D-Lists and used in D-Links. When working with SAP BW, you can use a concatenated query item to build a D-List in Analyst. However, when you create a link, either in Analyst or Contributor, then the concatenated query item cannot be used. Instead, use one of the underlying query items for the source and use a substring on the target dimension. When applying a filter in Framework Manager, you specify how it is used by selecting a usage value. To see the filtered data when publishing a package in Planning, select Always or Optional. See the Framework Manager User Guide for more information.

Recommendation - Hierarchy
These recommendations will help improve performance when working with the SAP BW import process. Use manageably sized dimensions when importing SAP BW data. This is because Planning relies on lookups against the SAP BW hierarchies during the import process, so larger hierarchies slow down the import process. This may require modelling in SAP BW since it is at a higher level of detail than the Planning process requires. Where possible, take data from the lowest level in the BW hierarchies. This is because data is taken from the fact table level and aggregated to the level selected in the Planning link. The

User Guide 89

Chapter 6: Importing Data from Cognos 8 Data Sources further up the hierarchy that members are mapped into Planning, the more aggregations are needed to be recreated during the import process. This may require modelling in SAP BW since it is at a higher level of detail than the Planning process requires.

Recommendation - Hiding the Dimension Key Field

When working with SAP BW data, the Dimension Key field for any dimension should be hidden in the Model (not the package) - both for the OLAP and Detailed Fact Query Subject access before the package is published. It is not intended for direct use from within Cognos Planning.

Working with Packages

To avoid a high number of Query Subjects and Query Items when working with and creating packages in Planning, you should make them as specific as possible so they contain only objects that are useful to a Planning user. Using a naming convention may also be useful, like using Planning as a prefix for your packages. For advanced users, you could also create a single package that holds all of the source objects.

90 Analyst

Chapter 7: D-Lists
Think of a D-List as a field in a database. The items contained in a D-List should be related to each other so that their relationships can be placed into formulas that proceed down the rows or across the columns. A D-List is a list of related items that can be put into formulas that proceed down the rows or across the columns of a D-Cube. Commonly used D-Lists include profit and loss items, months, divisions, products, customers, and cost centers. In addition to the items that make up the row, column, and page label, a D-List also contains formulas. You can use letters, numbers, punctuation marks, and spaces in D-List item names. However, you should avoid using the following: The semicolon (;) because it is used in special calculation formulas named built-in functions (BiFs). The at sign (@) and braces ({}) because these are used in formulas, built-in functions, and macros. The brackets ([]) because this naming convention is used to mark D-List formatted items, which appear as virtual dimensions in the D-Link editor.

Wildcard characters like * and ? can be used, but caution should be used when importing from a source that has item names without the wildcard characters. Use a local or loaded Allocation Table. You can also make the link using match descriptions to avoid any potential problems. See "Use Wildcard Characters in Local Allocation Tables" (p. 244). D-Lists that contain calculations can have those calculations force to zero. This means that if the calculation result is zero or if the result is nonsensical, the cell displays blank. This option is particularly useful for D-Lists with multiple calculations.

Open a D-List
You can open a D-List directly from the File menu or from a D-Cube.

Steps
1. From the File menu, click Open, D-List. 2. If you want to open a D-List from a D-Cube, right-click a D-List label, and then select Edit D-List from the list.

Create a D-List
Create a D-List to define the items that make up the row, column, and page labels. D-Lists can also contain formulas that proceed down the rows or across the columns of a D-Cube. User Guide 91

Chapter 7: D-Lists Alternatives to typing items manually are available. For more information, click a link below. Create an Import Link into a D-List (p. 124) Import Items from ASCII Files into a D-List (p. 126) Import D-List Items from Mapped ASCII Files into a D-List (p. 127) Import items from D-Cube data (p. 128) Import items from an ODBC source (p. 129) Import D-List items from Another D-List (p. 125) Import D-List items from a Cognos package (p. 130) Paste D-List Items from a Spreadsheet Database or Word Processor (p. 125)

For long lists, we recommend that each item consist of a code followed by a unique name (p. 141) (for example, A1234 salaries). For data imported from other sources, it is easier to match the unique names. D-List item names can be up to 50 characters long using letters, numbers, punctuation marks, and spaces. However, you should avoid the following characters in D-List names: Semicolon (;)The semicolon is used in special calculation formulas named built-in functions (BiFs). Brackets ([ ])These are used to mark D-List formatted items, which appear as a virtual dimension in the D-Link editor. At Sign (@)These are used in formulas, built-in functions (BiFs), and macros. Duplicate names are not allowed and are removed. Braces ({})These are used in formulas, built-in functions (BiFs), and macros. Duplicate names are not allowed and are removed.

Steps
1. From the File menu, click New, D-List. 2. In the Input New Items box, enter the items to include in the D-List. 3. Click OK. 4. To specify the attributes for each D-List item, click the attribute in the column you wish to specify, and then click Change item attributes. FormatOption Specify the data in the D-List as Numeric Format (p. 112), Date or Time Format (p. 114), D-List (p. 117), or Text (p. 118). Calculation. Define the calculations and built-in functions for D-List items (p. 93).

92 Analyst

Chapter 7: D-Lists Calc Option Specify D-List items to be weighted, specify time averages, or choose the calculation to force to zero (p. 106). 5. From the File menu, click Save. 6. Name the D-List. Note: The D-List name is case sensitive and must be unique. You can type up to 31 characters including spaces. 7. Click OK.

Formulas
You can create calculations if you need a comparison or ratio that does not exist in the data source. For example, you can calculate financial ratios, such as liquidity ratios, debt ratios, and activity. A calculation D-List is a generic term for any D-List containing formulas. D-List formulas come in four main categories: Numeric Date/Time D-List Text

These categories display against items in a D-List in the calculation column of the Format Attribute (p. 109) screen. You can arrange a formula however you want. The program ignores spaces, tabs, and carriage returns. For example, the program would consider the following three calculations identical. + Sales - {Rent and Rates} - Electricity + Sales - {Rent and Rates} - Electricity + Sales {Rent and Rates} Electricity

Import a Formula (CalcTexts)

You can import the calculations to apply to D-List items from any of the following sources:

User Guide 93

Chapter 7: D-Lists D-Cube data Mapped Ascii file Unmapped Ascii file ODBC (SQL database) Cognos package Another D-List Cognos Finance Impromptu Query Definition (IQD)

When setting up the import, your source data must contain a column with the names of the items against which the calculations are to be set, and a column containing the calculations themselves. The syntax must avoid spaces and symbols in item names. For example, if you were to use Margin % instead of Margin_percent as an item name, then when shown in the formula, margin % would have to be in braces {Margin %} to indicate to the program that this is an item name. While it is possible to import formulas from spreadsheets, it should be treated with caution. Generally, this facility is more useful for formulas generated from databases consisting of structured hierarchies. If you import formulas from spreadsheets, cell references in the formulas must be displayed and converted to text. First, you must ensure that the formulas all refer to cells in the same column or the same row and use + symbols rather than =SUM( ) in the formulas. Second, you must create range names for each cell based on the labels, apply the names to the formulas, and display the formulas in text format in the cells. Finally, this can be saved as a comma delimited (.csv) ASCII file and edited to remove leading = signs from the formulas. Zeros against detail items should be blanked out.

Steps
1. From the File menu, click New, D-List. 2. Click Import and select the import option you require. 3. At the Import of D-List Items screen, in the Select Attribute box, define the column containing the item names as Item Name and the column with the calculations as CalcTexts. 4. Make any other import settings you require. 5. Click OK. 6. Save the D-List, or use D-List > Implement to apply the calculations.

94 Analyst

Chapter 7: D-Lists

Preview or Print the Formulas

You can use the Print Preview function to view all the formulas before they are printed.

Steps
1. From the File menu, click Print or Print Preview. 2. Click the D-List tab. 3. Select the Calculations check box. 4. Click Preview. 5. Click the right or left arrow to scroll through the pages containing the formulas.

Create a Subtotal
When large amounts of data are shown, you can use subtotals to present data in a way that can be analyzed more conveniently. To add summaries, you need to specify the items for which you want to create a subtotal.

Steps
1. Open an existing D-List or create a new D-List containing the necessary items to subtotal. 2. Click the calculation cell of the item to which you want to add a subtotal. 3. Click Change item attributes. 4. Click Paste to select items specifically in the Selection dialog box. 5. Click Apply to test the syntax. 6. Save and close the D-List.

Enter a Formula into a D-List

To help you make better business decisions, you can summarize data or create conditional and statistical formulas for management analysis. Data is summarized using row or column calculations or by creating calculated D-List items. To select items needed in a formula, you can use the Search function. Items can be selected from either the Items Available list or the Items Included list. To use the Search feature, follow these guidelines: Wildcard characters of * and ? are allowed in the filter. Use a question mark (?) to represent any single character. Use the multiplication symbol (*) to represent any series of characters.

User Guide 95

Chapter 7: D-Lists Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters. The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria.

Steps
1. Open the D-List. 2. Click the calculation cell that you want to format. Then click Change item attributes. 3. Define the calculation: Type the formula in the Calculation box. You can enter calculations, BiFs, and conditional statements in the Calculation box. Remember that D-List items containing more than one word must be placed in braces to indicate that they are single variables. For example, {Rent & Rates} or {Margin %} If you want to select the items needed in the formula, click Paste. The arithmetic operators, plus {+}, minus {-}, multiply {*}, and divide {/}, should be entered at a later time. Select nonadjacent items by holding CTRL and clicking each item in the Items Available list. To move the selected items to the Items Included list, click Move. When you select single items from the Items Available list, double-clicking the item automatically moves it to the Items Included list. Tips: In the Select items to include list, you can select items using Search. This allows the use of wildcard characters. For example, if you have an item named P01, and you enter P01*, it will search for anything beginning with the characters P01. if you enter P?????????, it means search for any D-List item that starts with P and is ten characters long, including spaces. If you want to move items back to the Items Available list, select the items in the Items Included list and click Move. Expand explodes the constituent parts of a selected subtotal. 4. Click OK. 5. Type the operators. Ensure that D-List items of more than one word are in braces { } to treat them as a single variable. The program ignores spaces, tabs, and line returns. 6. Click Apply. 7. To calculate, from the D-List menu, click Implement.

96 Analyst

Chapter 7: D-Lists Implementing lets you test a formula in an open D-Cube before you save the D-List. Clicking Reset reverts the formula to the last saved version. 8. To save the formula without calculating, from the File menu, click Save. Formulas are shown in the Calculation column of the D-List attribute screen.

Edit a Formula
Depending on modeling requirements, you may need to modify an existing formula. You cannot edit a formula that is an output (p. 317) calculation from a built-in function (BiF). You are equally restricted in what you can do when editing a BiF calculation. You can change the BiF parameters (p. 320) but you cannot insert other items into or operate on the BiF formula.

Steps
1. Open a D-List. 2. Click the calculation cell of the item you want to edit. 3. Click Change item attributes. 4. In the Calculation box, edit the formula. 5. If you want to test the syntax, click Apply. 6. To calculate the formula, from the D-List menu, click Implement. Using the Implement function lets you test a formula before saving the D-List. If the formula is wrong, clicking Reset from the File menu reverts to the last saved version of the D-List. 7. If you want to save the formula without calculating, from the File menu, click Save.

Copy a Formula
You can copy a formula from one D-List to another to facilitate the creation of formulas that are similar among D-Lists.

Steps
1. Open the D-List containing the formula you want to copy (this is the source D-List). 2. In the Calculation box of the item in the source D-List, select the formula (or the section of the formula) from which you want to copy. 3. From the Edit menu, click Copy. 4. Close the D-List. 5. Open the D-List containing the formula to which you want to paste the copied formula (this is the target D-List). 6. Click the calculation cell of the item in the target D-List to which you want to copy the formula.

User Guide 97

Chapter 7: D-Lists 7. With the cursor in the calculation screen, from the Edit menu click Paste. 8. Click Apply. 9. From the File menu, click Save.

Remove a Formula
You can remove formulas that are no longer applicable to the D-Lists or required as part of the planning process. You cannot remove a formula that is an output calculation from a built-in function without removing the BiF formula first.

Steps
1. Open a D-List. 2. Select the calculation cell of the applicable item and click Change Item Attributes. 3. Select the calculation formula you want to remove. Existing formulas contain the following syntaxes in the calculation cell of the item: equal sign (=), Subtotal, Conditional, or BiF. 4. To remove the formula, click Clear. 5. To apply the changes to the item calculation cell, click Apply. 6. From the File menu, click Save.

Troubleshooting Formula Errors

To help with diagnosing problems with calculations, you can perform several checks. For example, you can verify if the expression includes all the details required to perform the calculation, if D-List items were double-counted, or if the formula exhibits circularity.

Check Formulas for Omission

You may want to check the subtotals that make up the grand total or the details that make up a subtotal. Viewing the details allows you to verify that the calculation expression includes the required D-List items. Examine the omitted items from a formula to ensure that the formula is valid and designed as intended.

Steps
1. Open the D-Cube containing the D-List you wish to check. 2. From the D-Cube menu, click Selections, Reselect. 3. Click on the tab for the relevant D-List.

98 Analyst

Chapter 7: D-Lists 4. Select a total and then click Expand(p. 157) to select the subtotals that form a part of the grand total. 5. Click Expand again to select the details that comprise the subtotals. Items that are not selected are omitted from the formula. 6. Scroll through the list and note the omissions. To make it easier, click Move to move the selected details to the Items Included list; this leaves only the omissions in the Items Available list.

Check for Double Counting in Formulas

In a hierarchical D-List, it is possible to check for double counting by using a simple D-Cube. Do not use this method when D-Lists use more complex calculations or there is no overall grand total.

Steps
1. In the D-List, create a check item and set it to be a sub-total of all the detail items. When setting the calculation use the option to show Detail items in the Show drop box. 2. Create a single item D-List. 3. Use the hierarchical D-List and the D-List created in step 2 to make a D-Cube. 4. Use D-Cube commands to set all detail items to 1 in the cube. The Grand Total in your hierarchy and the check item you inserted should now show the same value. If they do not, then some items have been omitted or double counted in setting the sub-totals in your hierarchy.

Check for Circularity

A formula exhibits circularity if x = function(y) and, directly or indirectly, y = function(x). Such circularity is not mathematically permissible and the program takes considerable steps to avoid circular formulas. When you select items to put in a formula, the selection screen hides the items causing circularity. For example, suppose you set up the formula:
Margin = {Margin %} * Sales/100 Costs = Sales - Margin

Then, at a later date, the formula you want to set up is:

Margin %= (Sales - Costs)/ Sales * 100

When you click Paste to select items for the calculation on Margin %, the item Costs would not be available for selection because it is indirectly a function of Margin% from the first formula. Hence, the formula would be circular.

User Guide 99

Chapter 7: D-Lists The program does not allow circularity within a D-List even if the application of a timescale removes the circularity. For example, suppose the built-in function, @Feed, is set up to feed the closing balance of one month to the opening of the next:
Close_n = Open_n + Inflow_n - Outflow_n Open_n = Close_n-1

where: n = period number Inflow is not allowed to be a function of the opening balance despite the fact that the presence of a timescale means that the formula is not strictly circular. The built-in function, @FeedParam, is specifically designed to avoid this.

View Formulas
You can view formulas for an individual cell in a D-Cube or view all formulas in a D-List. You can also view formulas for an individual cell in a D-Cube by pressing F7.

Steps to View a Single Formula

1. Open the desired D-Cube. 2. Click the cell containing the formula. 3. From the D-Cube menu click Show Formulae. A Calculations box appears and displays the formula. 4. When you finish viewing the formula, close the Calculation box. Alternatively, you can view D-List formulas. 5. In the Calculation box of a D-List, select the calculation cell of the D-List item. 6. Click Change item attributes.

Steps to View all Formulas in a D-List

1. Open a D-List. 2. From the File menu, click Print Preview. 3. Click the D-List tab. 4. Click the Calculations box. 5. Click Preview. 6. Click the right or left arrow to scroll through the pages containing the formulas.

100 Analyst

Chapter 7: D-Lists

D-List Conditional Formulas

Conditional or Logical Formulas
Logical functions are used to compare a value or the result of a formula with another expression. The logical operators available for conditional tests are IF, THEN, ELSE, AND, OR. The relational operators used are less than (<), greater than (<), equal to (=), greater than or equal to (>=), less than or equal to (<=), and not equal to (<>). Notes: The logical operators IF, THEN, ELSE, OR, and AND must be in capital letters and must be followed by parentheses ( ), to denote the start and end of the expression. You cannot enter the result of an IF THEN ELSE statement and expect breakback to give the reason for a particular result. Unlike simple mathematical formulas, conditional statements are not reversible.

The common syntax for a conditional formula is expressed as:

IF(test) THEN(expression) ELSE(expression)

AND Syntax
IF(test1 AND test2) THEN(expression) ELSE(expression)

OR Syntax
IF(test1 OR test2) THEN(expression) ELSE(expression)

The calculations included in a conditional statement can include further IF THEN ELSE calculations:
IF(Profit<=3525) THEN 0 IF (Profit<=6725) THEN 1 ELSE 2

Include the conditional statements in the required order because the calculation will return the result from the first condition satisfied. In the example above, if the profit is 3000 then this calculation will return the answer 0 as the first condition is satisfied.

User Guide 101

Chapter 7: D-Lists However, if the calculation cell were to read

IF (Profit<=6725) THEN 1 IF(Profit<=3525) THEN 0 ELSE 2

Then a result of 1 would be returned as, having found the first condition satisfied, the second condition is not considered. There are various other abbreviations For example, you can exclude the final ELSE statement entirely and it assumes ELSE 0. IF(Profit>3525) THEN 1 means:
IF(Profit>3525) THEN 1 ELSE 0

You can test the truth of a statement 1=TRUE 0=FALSE without putting in the IF THEN ELSE: (Item1=Item2) means:
IF(Item1=Item2) THEN 1 ELSE 0

IF(Item1) THEN 10 means:

IF (Item1<>0) THEN 10 ELSE 0

Example - Set Up a Conditional Formula

Suppose you want to group people by tax band using a conditional statement. The syntax would be:
IF(Profit<=3525) THEN 1 IF(Profit>3525 AND Profit<=6725) THEN 2 IF(Profit>6275 AND Profit<27825) THEN 3 ELSE 4

The result uses the conditional statement to group people by tax band: A more complicated example of a conditional formula is used to work out the tax amount:
IF(Profit<=3525) THEN (0) IF(Profit>3525 AND Profit<=6725) THEN ((Profit-3525)*.2) IF(Profit>6275 AND Profit<27825) THEN ((6725-3525)*.2 + (Profit-6725)*.23) ELSE ((6725-3525)*.2 + (Profit-6725)*.23)+(Profit-27825)*.40)

102 Analyst

Chapter 7: D-Lists

D-List Formatted Items in Formulas

Typically, text is used in formulas to display messages as a result of a conditional test such as OK or ERROR. However, the text must be D-List formatted text. You cannot type the conditional result text (such as OK or ERROR) directly into the formula as you can in a spreadsheet. The program stores text in a D-List formatted column as a number (named the item identification {IID} number). The formula must include a number as a result that refers to the IID number of a D-List item from another D-List. To view an IID, from the File menu click Print Preview, Preview. To find an IID, click the Summary Info button in the Analyst toolbar. In the example that follows, a flag has been set up to select names when the Grade or Division has been excluded accidentally. The item, Error-Flag, is a formula:
IF(Division=0) OR (Grade=0)) THEN 1 ELSE 2

However, rather than returning the number 1 or 2 according to the result of the conditional formula, the item Error-Flag has been formatted to accept text from another D-List. The other D-List contains only two items: ERROR and OK, which have identification numbers of 1 and 2, respectively. So when the result of the formula gives the answer 1, it looks up the identification number 1 and displays ERROR. Similarly, when the result of the formula gives the answer 2, it looks up the identification number 2 and displays OK.

Create a Conditional Formula Using D-List Formatted Text

The procedure for setting up a formula using D-List formatted text is the same as for setting up any other formula except that the numeric result is converted to text by applying a D-List format to the item containing the result. To apply the D-List format to the conditional formula, you must: assign a conditional formula to a D-List item create a separate D-List with a list of the text you want to display apply a D-List format

Steps
1. Open or create the D-List that you want to format to D-List formatted text. 2. Click the calculation cell of the item you want to format. 3. Click Change item attributes. 4. Create the formula in the D-List as a normal logical formula. 5. To test the syntax, click Apply. If the syntax is correct, the word Conditional appears in the calculation cell of the D-List item. 6. From the File menu, click Save. User Guide 103

Chapter 7: D-Lists Note: You may have to set conditional formulas to Low in the Priority box so that the totals add up correctly. The priority sorts conflicting formulas near the edges and corners of D-Cubes where calculations must be carried out in a specific order. You must consider this issue more than you would in a two-dimensional spreadsheet. In the event of a conflict, the higher priority formula is calculated last; therefore, its result is used. 7. To create a separate D-List with a list of the text you want to display, from the File menu, click New, D-List. 8. Type the item names, and click OK. 9. From the File menu, click Save As. 10. Name the D-List. 11. From the File menu, click Close. 12. In the D-List that requires formatting, click the Format cell of the item you want to format (the same item that contains the conditional formula), and then click Change item attributes. 13. In the Attribute box, click D-List and then select the library containing the desired D-List. 14. In the Available D-Lists box, select the D-List, and click Apply. The word D-List appears in the format cell of the item. 15. From the File menu, click Save. The formatted column converts the numeric result from the chosen D-List into text according to the identification number of the items contained therein.

Formula Priority
Priority conflicts can occur when a particular cell has a list of several formulas from which it must choose. Typically, this can occur when using logical IF THEN ELSE operators and percentages. The program can perform the calculation of the total either across the rows or down the columns, which can produce different results. For example, the percentage of the total is not the same as the total of the percentages. Setting priorities tells the program which formula to use in the event of a conflict. The program always uses the formula with the higher priority. Formula priority can be set to High, Medium, or Low.

View the Formula Priorities

View formula priorities to verify that the correct priority is set. The priority sorts conflicting formulas near the edges and corners of D-Cubes where calculations must be carried out in a specific order. You must consider this issue more than you would in a two-dimensional spreadsheet. In the event of a conflict, the higher priority formula is calculated last; therefore, its result is used.

Steps
1. Open the appropriate D-Cube. 104 Analyst

Chapter 7: D-Lists 2. Click the D-Cube calculation cell of an item containing a formula, and then press F7. A text box appears displaying the formula used, together with a list of the formulas it has overridden. 3. Close the text box.

View Priorities in the Priority Box Steps

1. Open the D-List. 2. Click the calculation cell of the item containing the formula. 3. Click Change item attributes. The priority is designated in the Priority box.

View Single Formulas

You can use this method to view all formulas, priorities, and other attributes.

Steps
1. Open the D-List. 2. From the File menu, click Print Preview, Preview.

Set Formula Priorities

The default priority for formulas is medium priority. If a conflict between two or more formulas with the same priority occurs, the program uses the formula contained in the earlier D-List. The order of the D-Lists is the order in which the D-Lists were chosen when the D-Cube was created. Calculations in the first D-List are calculated first and therefore are overridden by those in the later D-Lists, which are calculated last.

Steps
1. Open the D-List. 2. Click the calculation cell of the item for which you want to set the priority. 3. Click Change item attributes. 4. In the Priority box, change the priority of the formula to Low, Medium, or High. 5. Click Apply. 6. Save the D-List.

User Guide 105

Chapter 7: D-Lists

Apply a Time Average

You must define certain items in the calculation D-List as time averages so they give sensible results when calculating year-end totals or other subtotals. There are four kinds of time averages: Time Average = sum / number of periods. First period = use the data from the first period in the time formula. Last period = use the data from the last period in the time formula. Zero = displays as zero. Do not try to put a time average on a timescale D-List. Put the time average on a calculation D-List instead. The first and last time averages refer to the first and last items in the D-List formulas, not necessarily the chronological order. For example, if the formula is Q1=Feb+Jan+Mar, the first period is Feb not Jan.

Steps
1. Open or create a D-List containing formulas (not a timescale D-List) 2. Click the Calc. Option cell of the item to which you want to apply the time average. 3. Click Change item attributes. 4. In the Calc. Option list, click Time averages. 5. In the Available functions box, select one of the following options: Time average First period Last period Zero

6. Click Apply. 7. Save the D-List.

Weighted Averages
All items that are percentages, ratios, prices, or performance measures or items that can be expressed on a per unit basis must be set as weighted averages. This ensures that an item is correctly subtotaled and lets you breakback over subtotals. Weighted averages affect how an item is summed across any other dimension.

106 Analyst

Chapter 7: D-Lists

Quarter 1
Units Sold Price Sales Value 50 5 250

Quarter 2
50 6 300

Quarter 3
100 7 700

Quarter 4
50 6 300

Full Year
250 ? 1550

The Price for the full year is clearly not 5 + 6 + 7 +6 (=24). To calculate it we need ((5 x 50) + (6 x 50) + (7 x 100) + (6 x 50) )/ (50 +50 +100+50) =1550/250 = 6.2 The item Price must be set as a weighted average, weighted by Units Sold.

Choosing Which Item to Weight By

Generally, if D-List item A is a formula: A = B / C. Then item A should be weighted always by item C, the denominator, even if the relationship between the items is expressed differently. For example, the calculation above could be arranged such that B is the formula result: B = A * C. Item A still should be weighted by item C. A common example is a D-List containing the items Sales, Price, and Units:Price = Sales/Units. Price must be a weighted average weighted by Units.

Apply a Weighted Average

Weighted averages are applied by setting the D-List items to weighted averages.

Steps
1. Open or create a D-List containing formulas (not a timescale D-List) 2. Click the Calc. Option cell of the item to which you want to apply the weighted average. 3. Click Change item attributes. 4. In the Calc. Option list, click Weighted Averages. 5. In the Items to weight by box, select an item to weight by. 6. Click Apply. 7. Save the D-List.

User Guide 107

Chapter 7: D-Lists

Override a Weighted Average

It is possible to override a weighted average so that a total across another dimension uses straight addition instead. In the example shown below, a zero was added to the calculation of Total 1. Even though Unit Price has been set up as a weighted average weighted by Units, Total1 adds the prices together: 10 + 7 + 8 + 12 = 37. The annual total (Year) uses the more common weighted average: Year = Q1 + Q2 + Q3 + Q4 Total1 = Q1 + Q2 + Q3 + Q4 + 0

Q1
Unit Price Units Sold 10 50

Q2
7 100

Q3
8 200

Q4
12 50

Year
8.5 400

Total 1
37 400

In this example the weighted average is set on the item Unit Price in the rows D-List. The overridden total, Total 1, is in the timescale D-List forming the columns.

Steps
1. Open the D-List containing the total where you wish to override the weighted average. This might be a total in a timescale D-List for example. 2. Click the calculation cell of the item with the calculation. 3. Click Change item attributes. 4. Add a zero to the calculation. Adding a zero uses a straight total rather than a weightedaverage.

Force to Zero
Applying this average to any D-List item will cause any calculation on it in another D-Cube dimension to give a result of zero. It is particularly useful where the item applies in the detail only and is irrelevant on a total. This setting is applied automatically to D-List and Date formatted items but may be removed manually if desired by changing the setting to None.

Remove Averages
Steps
1. Open the D-List containing at least one formula (not a timescale D-List) with an average. 2. Click the Calc. Option cell of the item of which you want to remove the average.

108 Analyst

Chapter 7: D-Lists 3. Click Change item attributes. 4. In the Calc. Option list, click None. 5. Click Apply. 6. Save the D-List.

Applying Local Formats to D-Lists

A format sets the form in which data displays and can be in numeric, date/time, or D-List (text) format. Use numeric formats (p. 112) to set decimal places, insert thousand delimiters, set braces for negative numbers, and set prefixes and suffixes. Use date and time formats to display dates and times (such as 6-Jul-99) as data in a D-Cube. Use D-List Formats (p. 117) to enter text, restricting the text to the codes and names displayed in a selected D-List. Free-text formats (p. 118) are allowed. You can name and save formats for repeated use.

Local vs. Global Formats

A local format (p. 110) involves formatting D-Lists only and applies to an individual row or column. Generally, you apply local formats in the Format Attribute screen. The Format Attribute screen lets you control the appearance of items in a D-List. The content of the Format Attribute screen depends on the format type selected in the Format type list. Some elements of the Format Attribute screen are common to all format types: Attribute list, Format Type list, Prev. and Next, Assign, Apply, Reset, Load, Save, and Save As. A global format involves formatting an entire D-Cube. Generally, you apply global formats by clicking Format on the D-Cube menu. Although the two screens are almost identical, a D-Cube format is a general format applied to all data in the entire D-Cube, not just a specific item from a D-List. However, a local format applied to an individual row or column has priority over the global D-Cube format.

Types of Formats
The format affects how the data appears. A Numeric format determines the number of decimal places, the appearance of negative numbers, commas separating thousands, blank cells rather than zeroes, and showing percentage signs or currency symbols before and after the number. A Date/Time format determines whether the date appears in hours, months, years, or any of the standard formats such as DD/MM/YY. A D-List format lets you type text contained in another D-List into the formatted row or column. A Text format lets you type any text.

User Guide 109

Chapter 7: D-Lists

Assign Local Formats

This feature is useful when you would like to assign one format to several items within a D-List rather than having to define and then apply the same format to each item.

Steps
1. Create a format. 2. Click Assign to assign a format to other D-List items in the Selection dialog box. 3. Select the items to assign the format to in the Items Available list. 4. Click Move to move the items to the Items Included list. 5. Click OK to return to the D-List edit screen. 6. Repeat as necessary.

Save a Local Format

This feature is useful when you want to save a format within a D-List to be used several times in other D-Lists rather than having to define and then apply the same format repeatedly.

Steps
1. Open or Create an appropriate D-List 2. Create a format (numeric (p. 112),date or time (p. 117), or D-List (p. 117)) or edit an existing format 3. In the D-List editor, click Save. Click Save As to save the format with a new name. 4. Select a library to which you will save the local format from the Libraries list. 5. Type a name in the Saved Format Name box. 6. Click OK to return to the D-List edit screen.

Load a Local Format

This feature is useful when you want to apply a saved format.

Steps
1. Open the appropriate D-List. 2. Click the format cell of the item you want to format. 3. Click Load. 4. Select a library from the Libraries list.

110 Analyst

Chapter 7: D-Lists 5. Select a name in the Saved Format Name box. 6. Click OK. 7. Click Apply. 8. Save the D-List.

Formulas and D-List Formatted Items

Although the D-Cube displays an item name from the format D-List in a D-List formatted cell, it actually stores a value. The underlying number in a D-List formatted cell is the item identification number (IID) of the item from the format D-List. Each D-List item is assigned an IID when it is first inputted and no amount of reordering or deleting items can change it (short of substituting with a new D-List). New items are given new IID numbers - not reassigned old unused numbers. A D-List formatted cell whose underlying value is zero, or a number that is not a valid ID in the format D-List, displays as a blank cell in the D-Cube. Both detail and formula items can be D-List formatted. If a formula returns a number that is not a valid ID in the format D-List, the formula cell is blank in the D-Cube. To find an IID number, click the Summary Info button in the Analyst toolbar. You can display the item identification number of a D-List item by clicking the File menu, pointing to Print Preview, and then clicking the Preview button. The IID displays before the item name.

Format a Specific Row or Column

To format an individual row, column or page, open the relevant D-List and apply a format to a specific D-List item. This local format of a D-List item will always have priority over the global D-Cube format.

Steps
1. Open the D-List. 2. Click Change item attributes. 3. Select a format from the Attribute box as follows: A numeric format (p. 112) determines the number of decimal places, the appearance of negative numbers, commas separating thousands, blank cells instead of zeroes, and showing percentage signs or currency symbols before and after the number. A date or time format (p. 114) determines whether the date is displayed in hours, months, years, or any of the standard formats such as DD/MM/YY. A D-List format (p. 117) allows text from another D-List to be typed into the formatted row or column. A free-text format (p. 118) lets you type any string of characters or symbols.

4. Format the items accordingly.

User Guide 111

Chapter 7: D-Lists 5. Click Apply. 6. Repeat for other D-List items you wish to format. 7. Optional: Click Assign to assign a format to other D-List items. For example, the same numeric format applied to one specific item also can be assigned to another item. Click Assign, and then select the items to assign the format to. Select the items then click Move to move from the Items Available list to the Items Included list. Click OK to return to the D-List edit screen.

8. Apply the global format to the D-Cube. 9. From the File menu, click Save.

Numeric Formats
The numeric format lets you change how data displays. You can change the decimal places, assign currency such as $, , or FF, display negative numbers in brackets, hide zero cells, insert comma separators for thousands, or apply a scaling factor. Suffixes or prefixes are allowed - characters, numbers, punctuation marks, or percent signs (%) up to a recommended maximum of 10 characters. The default format is zero decimal places, comma delimiter active for thousands, brackets for negative numbers, a scaling factor of one, and zeros displayed when they display in a cell (Blank if zero is cleared). This displays the number 1234.0 as 1,234 and the negative number -1234.0 as (1,234). When you change the numeric format options, the Sample field updates showing how two sample numbers (1234 and -1234) will be displayed in a D-Cube. All values with a numeric format are right justified in the D-Cube. Where an item in a D-List has a scaling format applied, the behavior will be different in Analyst and Contributor. In Analyst the numbers are entered, ignoring any scaling applied in the formatting. So where an item is scaled to 1000s, if you type in 22k, it shows as 22 (i.e. 22k), but if you type in 22, it shows as 0 (0.022k), assuming that less than 2 decimal places are showing. In Contributor the numbers are entered as displayed - if the cell shows 1000 for an underlying value of 10, and you type in 1200, the new value shows as 1200 with the underlying value of 12.

Apply a Numeric Format

By applying different numeric formats, you can change the appearance of numbers. A numeric format does not affect the actual cell value that Analyst uses to perform calculations.

Steps
1. Ensure that the D-List is open and active. 2. Click the format cell of the item you want to format. 112 Analyst

Chapter 7: D-Lists 3. Click Change item attributes. An alternative is to double-click the format cell of the item. 4. Select Format from the Attribute list box, then click Numeric. 5. Set the decimal places (p. 113) and type the prefix and suffix (p. 192) for both positive and negative numbers. 6. Select Blank if zero if you want cells containing zero to be blanked out. 7. Select Use thousand delimiter to use a delimiter to show the number 1000000 as 1,000,000. 8. Type a numeral in the Scaling Factor(p. 257) box to display data in thousands, millions, and so on. Note: A scaling factor of 1000 will store the number 3333 as 3333.000 but display it as 3.333. If you set the decimal places to zero, it will display it as 3. This can cause confusion when adding three numbers X=A+B+C where A, B and C are all equal to 3333.000. With a scaling factor applied, this will be displayed as 3+3+3 =10 where the underlying calculation is correct as 3333+3333+3333=9999. 9. (Optional) Click Save and name the format. This allows you to apply the same format elsewhere. To load an existing format, choose Load and then select the name of the format. The Save As button allows you to edit an existing format and save it under a new name. 10. (Optional) The Assign button allows you to assign the current format to several other D-List items. 11. From the File menu, click Save.

Set the Decimal Places

Set how many decimal places to display. The default setting is zero.

Steps
1. Open a D-List. 2. Click the Format cell of the item you want to set decimal places to. 3. Select Numeric from the Attribute list. 4. In the Decimal Places scroll box, set the decimal places.

Set Scaling Factor within a D-List

Setting a Scaling Factor allows you to display numbers in round thousands, millions, and so on. The stored number is divided by the scaling factor to give the number displayed on the screen. The default scaling factor is 1, meaning that numbers are stored as they are displayed. For example, a scaling factor of 1000 applied to the number 1234.00 would display it as 1.23. The number that is stored by the program would always remain 1234.00.

User Guide 113

Chapter 7: D-Lists A scaling factor of 0.01 applied to the number 1234.00 would display the number as 123400.00. Again, the number that is stored by the program would always remain 1234.00. You must be careful with scaling factors. The program keeps the original number stored to many decimal places so there are no significant rounding errors. However, adding the numbers 1333 + 1333 +1333 = 3999 would give 1 + 1 + 1 = 4 when scaled by a factor of 1000. Applying the scaling factor is not the same as rounding to integers. Note: Use caution when applying scaling factors to individual D-List items because there is no indication in a D-Cube that scaling factors are set, and data can seem to be incorrectly calculated. Remember that you can set a scaling factor for an individual D-Cube. When you type a number into a cell formatted with a scaling factor, type the stored number, not the displayed number. The same rule applies when using D-Links to copy numbers into cells formatted with a scaling factor. You can also set scaling factors in D-Links.

Steps
1. Open a D-List. 2. Select the Format cell of the item you want to format. 3. Click Change item attributes. 4. From the Attribute list, click Numeric. 5. From the Scaling Factor box, type a scaling factor. Choose a factor between 1,000,000 (one million) and .000001 (one millionth). The default setting is 1 (no scaling). Normally, you want a D-Cube to display the actual value stored in a cell (the underlying number). You can use the scaling factor if you want the numbers displayed in the D-Cube to be scaled up or down from the stored value. The stored value is divided by the scaling factor to arrive at the displayed number.

Date and Time Formats

All values with a date or time format are left-justified in the D-Cube. There are three categories of date and time format. All date formats convert an underlying number (the date serial number) in the D-Cube grid into a date. Data entry in date-formatted cells in the D-Cube grid is restricted to valid dates (a date in the appropriate format).

Dates in Calculations
You can create calculations referring to date formatted items - they will calculate using the serial number. For example, you have a D-List containing two detail items, Start Date and Duration, and a formula item, End Date: {End Date} = {Start Date} + Duration Start Date is date formatted (DD/MM/YY).

114 Analyst

Chapter 7: D-Lists If Start Date displays 01/01/97 (serial number is 35,429), and Duration displays 2, then End Date will display 35,431. If End Date is date formatted (DD/MM/YY), it will display 03/01/97.

Date Formats
Thirty-two date format options are available, each of which is represented using a format code. The serial number for date formats containing a day, a month, and a year code (for example, YY-MM-DD, DD/MM/YY) is calculated from the number of days between January 1st, 1900 and the start of the period. For example, an item has been given the date format DD-Mon-YY. In the D-Cube, the date serial number and the displayed cell contents are related.

Serial Number
0 1 35,429 35,429.5

Cell Display
01-Jan-00 02-Jan-00 01-Jan-97 01-Jan-97

Other serial numbers are calculated differently. The day format is an example.

Serial Number
0 1 6 14 14.5

Cell Display
Mon Tue Sun Mon Mon

The following date formats show 4 digit years: DD-MM-YYYY MM-DD-YYYY DD/MM/YYYY MM/DD/YYYY DD.MM.YYYY

User Guide 115

Chapter 7: D-Lists MM.DD.YYYY DDMMYYYY MMDDYYYY

Time Formats
There is one time format, represented by the format code HH:mm. The serial number stored for a time-formatted cell is a fraction of a day. For Example:

Serial Number
0 0.5 0.75 1 1.25

Cell Display
00:00 12:00 18:00 00:00 03:00

Specific
The specific format provides the same twenty-four date formats provided by the date format, each supplemented with the time format. Serial numbers are calculated the same as the date. For Example: (Date/Time -Specific DD/MM/YY):

Serial Number
0 1 35,429 35,429.5

Cell Display
01/01/00-00:00 02/01/00-00:00 01/01/97-00:00 01/01/97-12:00

116 Analyst

Chapter 7: D-Lists

Apply a Date or Time Format

The date or time format shows date and time serial numbers as date and time values, according to the type and locale that you specify.

Steps
1. With the D-List active, click the Format column of the item you want to format. 2. Click Change item attributes. 3. Select Format from the Attribute box and then click Date/Time. 4. Select Date, Time, Date/Time, and/or Blank if Zero from the Format section. Note: To display un-entered dates as blank (rather than 1st January 1900, which is the base date), select Blank if Zero. This option is available in Analyst and Manager, but is unavailable in Analyst for Excel. 5. Select a date or time format from the Available formats box. Dates may be added or subtracted in formulas. The calculation uses the stored number as the number of days or fractions of a day since January 1st, 1900 (Jan 1st, 1900 is stored as 0, Jan 2nd, 1900 has a stored number of 1, and so on). 6. (Optional) If you want the count to start a day earlier (so that January 1st, 1900 is stored as 1, January 2nd, 1900 as 2, and so on) click Date/Time in the Format section, then click End instead of Start. Then choose the format as usual. 7. From the File menu, click Save. The dates and times can now be typed directly into the formatted cells in the D-Cube.

Apply D-List Formats

A D-List format lets you type text from another D-List in a row or a column. The D-List format is a very powerful feature of Analyst. The format is used in database type functions to consolidate data in a similar manner to query-style reports. The format also can be used to provide look-up tables. When typing in text, the first character or two of a text entry is sufficient as long as it is not ambiguous. If you are unsure of what to type, type a question mark (?) and a drop down menu appears showing all the available items from the D-List. Free text format is not allowed because the text typed must correspond to an item in a D-List.

Steps
1. Open the D-List that contains the items you want to format to accept text. 2. Click the Format column of the item you want to format and then click Change item attributes. 3. Select D-List from the Attribute box. 4. Select a library from the Libraries box. User Guide 117

Chapter 7: D-Lists 5. Select a D-List from the Available D-Lists box. Only those items appearing in this D-List will be allowed in the formatted column. 6. Click Apply. 7. From the File menu, click Save. Tip: When typing in text, the first character or two of a text entry is sufficient as long as it is not ambiguous. If you are unsure of what to type, type a question mark (?) and a drop down menu appears showing all the available items from the D-List.

Apply Free-Text Format to a D-List Item

You can format a D-List item to accept free text of 50 characters or less. Text format has priority over time and numeric formats, but not over D-List formats. Text may be transferred to another D-Cube using a D-Link as long as the target D-List item is also a text format. Formula cells cannot accept free text and will always display blank.

Steps
1. Open or create a D-List. 2. Click the format cell of the item you wish to format. 3. Click Change item attributes. 4. Select text from the Attribute list. 5. Save and close the D-List.

Timescale D-Lists
D-Lists containing items such as days, weeks, months, quarters, or years need to be defined as timescales. These are necessary for special built in functions (BiFs) that use time to apply calculations such as debtor days, stock-turn days, and creditor days to determine closing balances. Timescale D-Lists also are used for importing data containing dates into the correct period. They also can be used by the Grow command to grow a base value by a certain percentage per period (linear or compound). Typing Jan01 in a Period column automatically generates dates. Dates also may be imported from spreadsheets using CTRL+C to copy a selected range and CTRL+V to paste into the period column. Dates in Analyst run from 1950 to 2049. So if you type the two digit 49, it means 2049. But if you type 50, it means 1950.

118 Analyst

Chapter 7: D-Lists

Create a Timescale D-List

Steps
1. From the File menu, click New, D-List. 2. Type the date items (for example, Jan 00, Feb 00, Mar 00, and so on). 3. (Optional) Type the names of any subtotals required. 4. Click OK. 5. Set the calculations on any calculation item. 6. From the D-List menu, click Options. 7. Click the Timescale tab, and set the following options: For certain standard formulas, you need dates. Either set the dates by defining the start and end of each period in the format dd/mm/yy or set the months in the period column. Combinations of from and to dates and months in the period column are not permitted. Note: After you create your timescale D-List, check the timescale output. Ensure that the dates are correct according to what you set. For example, if you have the format as mm/dd/yyyy, some of the entries may switch to dd/mm/yyyy. If this occurs, manually change the From and To fields. For the built-in functions (BiFs), ytd (year to date) and de-ytd, you need a fiscal year start date. Type the start date and month in the Start of fiscal year box. For the built-in functions Drive, Drive1, Drive2, Outlook, DCF, ICF (discounted and inflated cashflow), Grow, Mix, and Stockflow; and for some of the options in @Time, you need a switchover date denoting the dividing point between past and present. Select the Use Switchover box and then type the date if you require the built in function to read the switchover setting from the D-List. You can use from, to, and period dates to define a time period. 8. If you want to use a generic monthly timescale (Jan, Feb, Mar), click Use as Timescale, and click OK. 9. From the File menu, click Save. 10. Name the D-List. Note: The D-List name is case sensitive and must be unique. You can type up to 31 characters including spaces. 11. Click OK.

User Guide 119

Chapter 7: D-Lists

Create a Custom Timescale

You can define the timescale by specifying the start date and the length of the time period in days. This method is much quicker if you have a weekly or a mixed timescale.

Steps
1. Open a D-List and choose D-List>Options. Click the Timescale tab and select the Use as timescale option. The timescale dates can now be set in two modes: Normal and Custom. 2. Choose whether you want to set the Normal or Custom mode: If you want normal mode, set the From & To dates manually or pick up on the D-List item name and the program fills in sensible From and To dates. If you want custom mode, set the length in days and the first From date.

Items of zero length are treated as non-time items and do not have a From and To date attached to them. This allows you to start the timescale at an item other than the first D-List item. You can also allow for non-time items by setting the length to zero. You can switch between the Normal mode and Custom mode.

Timescales and BiFs

All Built-in Functions (BiFs) are time-dependent. However, you should not set up BiFs in the timescale D-List. You should set up the BiF in the main calculation D-List. The BiF becomes active only when set up in a D-Cube against a timescale D-List. Usually, you should set up the D-Cube with the calculation D-List first and the timescale D-List last. This ensures that the timescale D-List has priority in the event of conflicting calculation formulas. If the BiF formula accidentally is given a higher priority, the result is zero in time totals such as quarterly or annual totals.

Common Errors in Timescales

The most common error in defining timescale D-Lists is failing to define the periods for items that require them. This gives the BiF an ambiguous calculation when setting results using inputs such as debtor days, switchover dates, and so on. Another common error is to define the timescale D-List as a mixture of generic months (Jul, Aug, Sep, and so on) and specific dates (for example, 01/05/02 to 31/05/02). Choose only one date format. Also, remember to use D-List as a parameter in the BiF formula if you want to use the switchover date defined in the D-List.

Set Periods of Uneven Lengths

Occasionally, you must use the number of days in a period to take account of periods of unequal length. For example, in the built-in function, @DelayStock, you should set the indicator to 1 for days if the periods are not equal in length. If you do not define the dates in the timescale D-List, 120 Analyst

Chapter 7: D-Lists the program assumes that all periods are equal. The default days setting for a month uses an average of 30.42 days (365/12), which can lead to inaccuracies.

Steps
1. Open the timescale D-List. 2. From the D-List menu, click Options. 3. Ensure that the From and To dates are defined correctly for each period. 4. Click OK. 5. Save the timescale D-List.

Copy an Existing D-List

You can make an exact copy of an existing D-List so that the formulas and formatting are copied with the item names.

Steps
1. Open the D-List 2. Select the D-List you want to copy. 3. Click OK. 4. From the File menu, click Save As. 5. Type the new name. 6. Click OK.

Edit a D-List
You can edit items names and related attributes. You can edit other features, such as timescales, import links, subheaders, and masks definition. A mask is used to hide individual items within a D-List or to prevent people writing over specified items. This is particularly useful when you are operating on a network and want to allow limited access to large D-Cubes. You can be quite specific about the level of security applied to each item by means of applying an item called a mask. A mask contains a security pattern with a list of users and their access rights. It can be attached to one or more D-List items. You may customize the mask to give each user a key to unlock the restrictions. The choices are Read-only, Read/Write, or Invisible. Items that are set to Invisible will not appear on the selection screen at all, whereas items marked Read-only will appear on the screen but can not be over-typed or changed except by some indirect method such as a breakback. Read/Write access means that the items can be changed as usual.

User Guide 121

Chapter 7: D-Lists These settings can be defined for each user or for groups of users. If a user is also a member of a group for which access rights have been defined, he assumes the highest level of access available. Steps Open the D-List. To edit item names, click on them and overtype with the new names (p. 123). To add items, from the D-List menu, click Add Items (p. 123). It is possible to add items to a D-List from different sources. For more information, click a link below. Create an Import Link into a D-List (p. 124). Paste D-List items from a spreadsheet database or word processor (p. 125). Import D-List items from another D-List (p. 125). Import items from unmapped ASCII files into a D-List (p. 126). Import D-List items from mapped ASCII files into a D-List (p. 127). Import items from D-Cube data (p. 128). Import items from an ODBC source (p. 129). Import D-List items from a Cognos package (p. 130)

To delete items, from the D-List menu, click Delete Items (p. 131). To change the attributes of an item, select the item you want to edit and then click Change item attributes. Edit the attribute of the items you want to change. Formats (p. 109) Averages, such as Time (p. 106) and Weighted (p. 106) Formulas (p. 93)

To edit other features of the D-List, from the D-List menu, click Options, and then the appropriate tab. Timescales (p. 118) Import Links (p. 124) Sub headers (p. 145) Unique names (p. 141) Security (Masks)

Edit the features you want to change and then click OK. Implement the changes and save the D-list (p. 131).

122 Analyst

Chapter 7: D-Lists

Edit D-List Item Names

Change the D-List item names to reflect a name that is more obvious to users. You can use letters, numbers, punctuation marks, and spaces in D-List item names. However, you should avoid using the following: The semicolon (;) because it is used in special calculation formulas named built-in functions (BiFs). The at sign (@) and braces ({}) because these are used in formulas, built-in functions, and macros. The brackets ([]) because this naming convention is used to mark D-List formatted items, which appear as virtual dimensions in the D-Link editor.

Note: If you change D-List item names, you should check any D-Links in which the D-List is used. If the D-List is paired with a different D-List on a match descriptions basis then the item you have renamed will no longer match.

Steps
1. Open the D-List. 2. Click the item you want to edit. 3. Double-click the item name and type the new or edited name. Note: To split long column headings, double-click the item you want to edit in the Item Name column. Use the pipe symbol "|" (shift+\) to denote a line break so that the column heading displays on two lines. You can have more than one line break. The pipe symbol does not display on the screen. 4. From the File menu, click Save.

Insert items from a D-List

You can insert items from a D-List while in a D-List or D-Cube.

Steps
1. Choose to insert items while in a D-List or D-Cube To insert from a D-List, from the D-List menu, click Add Items and select Input. To insert from a D-Cube, right-click your mouse on the D-List dimension, and then click Insert Items. The Input new Items screen allows you to type the new D-List item names and select the options you need, including whether to import items, and if so, what mode to import it by; where to place the new items, and a choice of Subtotals into which the new items may be inserted. 2. Type the D-List item names, or make your selections, and click OK.

User Guide 123

Chapter 7: D-Lists

Create an Import Link into a D-List

Use an import link to update the items in a D-List on a regular basis from a source file. This could be a monthly download of a file containing a list of account codes or a periodic review of product codes. After you create the link, you can run it by clicking the D-List menu and then click Update. This scans the source file and looks for any new items based on the unique part of the D-List, and rejects any duplicates. It then sorts the new items in a predefined manner or inserts them individually as desired.

Steps
1. Open the D-List. 2. From the D-List menu, click Options, Import link tab. 3. Choose the type of source file from the Import From drop down box (click one of the following links for more information). ASCII file (p. 127) (text, .csv, .txt or .prn files, and so on). D-List (p. 125) (to import items from another D-List). ODBC (databases) (p. 129). Cognos package (p. 130) D-Cube (p. 128) (to import items from another D-Cube). Finance. No Import Link (to turn off the default setting by selecting).

4. Choose the import mode (p. 132), from the drop down box. If using Update mode the Remove Obsolete check box will become active. Select it to keep specified items. 5. Choose the position and sort order of the items from the Location/Sort Order drop box (p. 143). 6. Use the Subtotal drop box if you wish to insert the new items into existing subtotals in the D-List (p. 145). Whenever you import items to a D-List, or create a new D-List by importing from an eligible source, you will be offered the option to turn this import into an import link for the D-List. If you answer Yes to this question, it will overwrite any existing import link.

Run an Import Link into a D-List

Running an import link into a D-List will update the D-List with the new items by reading straight from the source file. If the import link is run to a closed D-List by means of a macro, then any

124 Analyst

Chapter 7: D-Lists changes will be saved automatically. Depending on the settings in the import link, the existing items could be renamed or deleted altogether, so use caution when running these links.

Steps
1. With the D-List active, from the D-List menu click Update. 2. Position the new items. Note: Skip this step unless the position is set to Select in the Where box. In the Selection window, select items in the Items Available list and choose the insertion point by clicking the Items Included list. Click Move >> to insert the selected items below the chosen insertion point. If duplicates exist that are solely based on the unique part of the D-List item, the program rejects the duplicate items. 3. Check any formulas. 4. From the File menu, click Save.

Paste Items from a Spreadsheet, Database, or Other Text Source

You can copy text into a D-List from another program by pasting it in using the Microsoft Windows clipboard.

Steps
1. In the source program, select the items you want to copy. 2. Copy the items to the Windows clipboard by pressing Ctrl+C. 3. Return to Analyst. Create a new D-List, or for an existing active D-List, from the D-List menu, click Add Items and then click Input. 4. In the Enter item names text box, paste items from the clipboard by pressing Ctrl+V. 5. From the File menu, click Save. 6. Name the D-List if a new D-List was created. 7. Click OK.

Import D-List Items from Another D-List

You can create a new D-List or insert items into an existing D-List by importing items from another D-List. Optionally you may also import formulas, formats and calculation options (such as weighted averages). The source data for the D-list item must be a single page of the D-Cube. It can consist of several columns of D-List formatted data and may also include the rows D-List.

User Guide 125

Chapter 7: D-Lists The procedure below assumes that you are importing D-List items into a new D-List. If, however, you are importing D-List items into an existing D-List, you must open the D-List, and then from the D-List menu, click Add Items, and then start at step 2.

Steps
1. From the File menu, click New, D-List. 2. Click Import and then click Import From Another D-List. 3. Select the D-List containing the source data. 4. Make a selection from the D-List items. Ctrl-click to select non-adjacent items. A blank selection will import all the items. 5. Click OK. 6. Look at the Import of D-List Items dialog box: Click Import Mode (p. 132), and select either Append or Update. Click Subtotals and specify a subtotal, or choose either <None> or <Allocate>. Click Where to select where you would like the items from the ASCII file placed in the D-List. Click Select Attribute to choose from the following: Skip, Item name, Parent, Parent 1 through Parent 8. 7. In the import option box make selections to determine the items to be imported. If you wish to import formulas and format attributes, you must check the relevant boxes. 8. Click OK. 9. Choose whether you want to turn this import into an import link for the D-List. If you click Yes, it will overwrite any existing import link. 10. Click OK to import the items, and then save and close the D-List.

Import D-List Items from Unmapped ASCII Files

To import from D-List items from an unmapped ASCII file, you must specify the delimiter used in the ASCII file.

Steps
1. From the File menu, click New, D-List. - or From the File menu, click Open, D-List, and select the appropriate D-List. 2. From the D-List menu click Add Items. 3. Click Import and then select Import Unmapped ASCII. 126 Analyst

Chapter 7: D-Lists 4. Browse for the correct file and then click Open. 5. Look at the Apply Structure dialog box and do the following: Select Use Delimiter and then specify comma, semicolon, colon, tab, or space as the delimiter 6. Look at the Import of D-List Items dialog box: Click Import Mode (p. 132), and select either Append or Update. Click Subtotals, and either specify a subtotal or choose either <None> or <Allocate>. Click Where to select where you would like the items from the ASCII file placed in the new D-List. Click Select Attribute to choose from the following: Skip, Item name, Parent, Parent 1 through Parent 8 or Calc Texts. 7. Click OK. 8. Choose whether you want to turn this import into an import link for the D-List. If you click Yes, it will overwrite any existing import link. 9. From the File menu, click Save. 10. Name the D-List if necessary. Note: The D-List name is case sensitive and must be unique. You can type up to 31 characters including spaces. 11. Click OK.

Import D-List Data from Mapped ASCII Files

Before you import D-List data from mapped ASCII files, you must first create the file map from which the data is imported.

Steps
1. From the File menu, click New, D-List. - or From the File menu, click Open, D-List, and select the appropriate D-List. 2. From the D-List menu click Add Items. 3. Click Import and select Import Mapped ASCII File. 4. Select a file map, and then click Open. 5. From the Import of D-List Items dialog box: Click Import Mode(p. 132), and select either Append or Update. Click Subtotals and specify a subtotal, or choose either <None> or <Allocate>.

User Guide 127

Chapter 7: D-Lists Click Where to select where you would like the items from the ASCII file placed in the new D-List. Click Select Attribute to choose from the following: Skip, Item name, Parent, Parent 1 through Parent 8, or Calc Texts. 6. Click OK. 7. Choose whether you want to turn this import into an import link for the D-List. If you click Yes, it will overwrite any existing import link. 8. From the File menu, click Save. 9. Name the D-List if necessary. 10. Click OK.

Import D-List Items from a D-Cube

You can create a new D-List or insert items into an existing D-List by importing items from a D-Cube. The source data for the D-List item must be a single page of the D-Cube. It can consist of several columns of D-List formatted data and may also include the rows D-List. The procedure below assumes that you are importing D-List items into a new D-List. If, however, you are importing D-List items into an existing D-List, you must open the D-List, and then from the D-List menu, click Add Items, and then start at step 2.

Steps
1. From the File menu, click New, D-List. 2. Click Import, and then select Import D-Cube Data. 3. Select the D-Cube containing the source data. 4. Make a selection from the D-Cube dimensions which consists of one page only and columns of formatted data. 5. Click OK. 6. From the Import of D-List Items dialog box: Click Import Mode (p. 132), and select either Append or Update. Click Subtotals, and either specify a subtotal or choose either <None> or <Allocate>. Click Where to select where you would like the items from the ASCII file placed in the new D-List. Click Select Attribute to choose from the following: Skip, Item name, Parent, Parent 1 through Parent 8 or Calc Texts.

128 Analyst

Chapter 7: D-Lists 7. Click OK. 8. Choose whether you want to turn this import into an import link for the D-List. If you click Yes, it will overwrite any existing import link. 9. Click OK to import the items, and then save and close the D-List.

Import D-List Items Using ODBC

You can create a new D-List or insert items into an existing D-List by importing items from a database or spreadsheet using an ODBC link. Before importing D-List items using an ODBC link, you must check that the ODBC driver has been correctly installed and that a data source has been set up for the spreadsheet or database you want to access. The procedure below assumes that you are importing D-List items into a new D-List. If, however, you are importing D-List items into an existing D-List, you must open the D-List, and then from the D-List menu, select Add Items, and then start at step 2.

Steps
1. From the File menu, click New, D-List. 2. Click Import, and then select Import from ODBC (SQL database). 3. Select an ODBC source, then click Connect. If required, you may need to log on with your ID and password. 4. Select the table and column that contain the items to import. You can click Fetch to preview the column. 5. Optional: Click Create SQL to create a SQL statement. Experienced SQL users can edit this statement or type a SQL statement directly into the text box. For example, to combine two columns into a single D-List item, type a SQL expression such as Select ProductID & ProductName from Products. 6. Click OK. 7. From the Import of D-List Items dialog box: Click Import Mode(p. 132), and select either Append or Update. Click Subtotals and specify a subtotal, or choose either <None> or <Allocate>. Click Where to select where you would like the items from the ASCII file placed in the new D-List. Click Select Attribute to choose from the following: Skip, Item name, Parent, Parent 1 through Parent 8, or Calc Texts. 8. Click OK.

User Guide 129

Chapter 7: D-Lists 9. Choose whether you want to turn this import into an import link for the D-List. If you click Yes, it will overwrite any existing import link. 10. Click OK to import the items, and then save and close the D-List.

Import D-List Items From a Cognos Package

You can create and run an import link into a D-List using a Cognos package as a source. After you create the link, you can run it by clicking the D-List menu and then click Update. This scans the source file and looks for any new items based on the unique part of the D-List, and rejects any duplicates. It then sorts the new items in a predefined manner or inserts them individually as desired.

Steps
1. Open the D-List. 2. From the D-List menu, click Options, Import Link tab. 3. Choose Cognos Package as the type of source file from the Import From drop down box. 4. In the Cognos Package section, you can click the ...button to select a Cognos package, or if you already have a Cognos package, you can switch to a different Cognos package and then select new Query Items. You can display a preview of the selected Query Items. Select the Display preview of selected query items check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items.

5. Choose the import mode from the drop down box. If using Update mode, the Remove Obsolete check box will become active. Select it to keep specified items. 6. Choose the position and sort order of the items from the Location/Sort Order drop box. 7. Use the Subtotal drop box if you wish to insert the new items into existing subtotals in the D-List. 8. Select an attribute from the drop box. 9. Optional: If you are editing an existing Import link, click Connect. 10. Click OK. Whenever you import items to a D-List, or create a new D-List by importing from an eligible source, you will be offered the option to turn this import into an import link for the D-List. If you answer Yes to this question, it will overwrite any existing import link.

130 Analyst

Chapter 7: D-Lists

Export a D-List as an e-List

You can export a D-List in a format that the Contributor Administration Console can use to import into an e-List.

Steps
1. Open the D-List. 2. From the D-List menu, click Export as E.List. 3. Choose a location to save the exported D-List. 4. Enter a name for which to save the exported D-List. 5. Click Save to export the D-List as an e.List. Note: The order of the items in the e.List is determined by the order of the items in the D-List item calculations, not the order that the items appear in the D-List itself. A macro called @ExportToEList is also available to automate this export process.

Implement Changes
If you make a change to a D-List, it is necessary to implement the change.

Step
From the D-List menu, click Implement Implement lets you see the effect of your proposed changes in any open D-Cube which uses the D-List, and still revert to the saved version in the event of an error. To revert to the saved version, from the D-List menu click Reset. - or From the File menu, click Save.

Delete items from a D-List

Deleting items from D-Lists should be done carefully because all data relating to each D-List item is deleted with it. If the D-List is used in several D-Cubes, it is deleted from all D-Cubes, not just the one you are working on. If the D-list is used as a dimension in a D-Link, you should check carefully to ensure that the D-link will still function correctly without the item you are deleting. In multi user systems, we recommend you check to see who is using a particular D-List before deleting items from it.

Steps
1. Choose whether to delete items while in a D-List or D-Cube: If from a D-List, from the D-List menu, click Delete Items. If from a D-Cube, right-click your mouse on the D-List dimension, and click Delete Items. User Guide 131

Chapter 7: D-Lists 2. In the Selection dialog box, select the items you want to delete and then click Move >>. 3. Click OK. This message appears: X items to be deleted. Do you want to proceed? 4. Click Yes to delete or No to cancel. 5. Save the D-List or D-Cube to make the deletion permanent. Tip: A shortcut for deleting an individual D-List item is to click the row numbers in the D-List attribute screen and then press Delete.

Import Mode
When importing items into a D-List, the import mode determines how to insert new items which may contain a unique code into a D-List.

Unique Names
A D-list item name may consist of a unique code, a specified number of characters in length followed by a description (p. 141). If this is the case and the source data for the import contains an item with the same unique code as an existing D-List item, but a different description, then Append mode will leave the existing description unchanged. Update mode will change the item to use the description in the source data.

Example - Import Modes

This example illustrates the different behaviors of the four basic import modes Append Update Update+Remove Obsolete Update+Remove Obsolete but Keep

In the example shown, the original D-List prior to copying contains 4 items: A, B and C adding to a subtotal X total. No special formatting or calculation options exist on the original D-List, but the unique code portion has been defined as being the first character.
A B C X total = A+B+C

132 Analyst

Chapter 7: D-Lists The source D-List has 4 items: A product, D product, E product adding into X total. In each case all the items from the source D-List are copied together with their formulas and formats. The sort order is set to 'hierarchical' and no subtotal is chosen. In each case, the numeric formats and the formulas are copied across.
A product D product E product X total= A product+ D product+ E product

When copying from ASCII, ODBC or D-Cube data, the source file has two columns consisting of an item and its parent.
A product X total D product X total E product X total

Copying from Another D-List

When copying from another D-list, formulas are replaced in Update mode, left unchanged in Append mode. The descriptions are always modified in Update mode, but not in Append mode. In Update mode, you are allowed to remove obsolete items, but can prevent the deletion of selected items by pressing the Keep button. Note: The behavior of Keep does indeed keep item B in the D-List, but does not keep it in the formula X total. Even if you had included X total in the selection of items to Keep, its formula and format would still have been updated.

Target D-List Source Target D-List After Copying D-List: Copy before copying all items Append Update Update+Remove Obsolete Update+Remove Obsolete, but KeepB
A B C A Product D product E product A B C D product E product A product D product E product A product D product E product A product

X total =A + B X total = A +C product + D product + E product

X total =A + B X total = A +C product + D product + E product

X total = A product + X total = A product + D product + E product D product + E product

User Guide 133

Chapter 7: D-Lists

Target D-List Source Target D-List After Copying D-List: Copy before copying all items Append Update Update+Remove Obsolete Update+Remove Obsolete, but KeepB
D product E product B C B

Importing from ASCII files, ODBC sources, Cognos Packages, or D-Cube data
When importing from ASCII files, D-Cube data, ODBC sources, or Cognos packages using macros, simple subtotals are combined in both Update and Append mode. The descriptions are always modified in Update mode, but not in Append mode. In Update mode, you are allowed to remove obsolete items, but can prevent the deletion of selected items by pressing the Keep button.

Target D-List

Source File

Target D-List After Running Macros

Item Name Parent

Append

Update

Update+Remove Update+Remove Obsolete Obsolete,but Keep B

A B C X total = A+B+C

A Product D Product E Product

X Total X Total X Total

A B C D Product

A Product B C

A Product D Product E Product

D Product E product A Product X total= A product+ D product+ E product B

D Product X total= A product+ D product+ E product E Product X total = A+B+C+D product+ E product

E Product X total = A+B+C+D product+ E product

134 Analyst

Chapter 7: D-Lists

Where Drop-Box
When moving or importing items, the Where box lets you define where new items are positioned. Top puts all the new items at the top of the list. Bottom puts all the new items at the bottom of the list. Select lets you position items individually using the selection screen. You must move each new item to the Items Included list by clicking Move >>. You can reposition the items with the arrow buttons on the right of the selection screen. The Reset button lets you start over if an error occurs. Alphabetical sorts the entire list alphabetically and numerically, including reordering existing items. Hierarchical automatically creates subtotals, totals, and grand totals according to the position of each item in a hierarchy defined in the source data.

Subtotals Drop-Box
The Subtotals drop-box lets you modify subtotal formulas to incorporate new items. The subtotal option is available only when the formulas consist of simple additions of items in the D-List. <None> does not change subtotal formulas. <Allocate> lets you set up an allocation table to allocate items into one or more subtotals. This is particularly recommended for long lists with multiple formula hierarchies.

A final option is for you to select a single subtotal from the list. This incorporates all new items into that subtotal formula.

Maintaining Hierarchies
You can create source files for hierarchical D-Lists in ASCII files, databases with ODBC connections or D-Cubes. In all import screens there is a sorting option called hierarchical. This groups newly imported D-List items with their subtotals.

Simple Hierarchies
You do not have to have each level of the hierarchy in a separate column. By defining the first column Item name and the second column Parent in the example below, cities add up into countries, add up into continents You can go straight from Item name to Parent 2 without an intermediate Parent being assigned.

User Guide 135

Chapter 7: D-Lists

Item Name
Ottawa Montreal Canada New York Rio de Janeiro Brazil

Parent
Canada Canada Americas Americas Brazil Americas

Create Hierarchies from an ASCII (Text) File

You can import items into a D-List and automatically create subtotals, totals, and grand totals according to the position of each item in a hierarchy defined in an ASCII or text file. Each item should be listed as a subtotal or total that each item belongs to. Using this method, you can create D-Lists as well as set up a D-List import link (p. 124) for ongoing maintenance.

Steps
1. From the File menu, click New, D-List. 2. Click Import and then select Import from ASCII-files. Note: If the ASCII file is a fixed-width text file, you need to set up a file map to define where each column of data starts and ends. In that case, you select Import from Mapped ASCII files. 3. Select the name of the ASCII file or file map to import. Note: If importing from a delimited ASCII file, select Use Delimiter and then select Comma as the delimiter. 4. Select the column containing the lowest level of the hierarchy and select Item name in the Select Attribute box. Then select the column containing the subtotals and select Parent in the Select Attribute box. At the next highest level of the hierarchy, select Parent 2 (grandparent). 5. Repeat until all columns have been assigned to a level. 6. Set the import mode (p. 132). 7. Click OK to import the items and then save and close the D-List.

Multiple Independent Hierarchies

Multiple independent hierarchies can be set up provided the relationship is defined by labeling one column containing the Item name and a second column containing the Parent. Hierarchies do not have to be branches of the same tree; they can be totally independent of each other.

136 Analyst

Chapter 7: D-Lists For example, the ASCII file shown below would have the first column defined as Item name and the second column defined as Parent. One hierarchy adds up the products by sub-totalling into countries. A second independent hierarchy adds up the products into soft and hard cheese types. The item names do not have to be in any specific order.

Camembert
St Paulin Edam Roquefort Camembert St Paulin Edam Roquefort

French cheeses
French cheeses Dutch cheeses French cheeses Soft cheeses Hard Cheeses Hard cheeses Soft cheeses

Multiple Column Source File

As an alternative to maintaining your data in two columns in your source file (which may be an Ascii file, a database or a D-Cube) you can use multiple columns defined as Item Name, Parent, Parent2 etc. There does not need to be an entry in every intermediate parent column.

Item name
Ottawa Montreal New York Rio de Janeiro

Parent
Canada Canada

Parent2
Americas Americas Americas

Brazil

Americas

Import D-Cube Data

You can update a D-List from the hierarchical data contained in a D-Cube. You can use the same data to maintain both the e-list in Contributor and the equivalent D-List in Analyst. By maintaining them from the same source, you ensure that they remain in step when the hierarchy changes.

User Guide 137

Chapter 7: D-Lists

Example: Create and Maintain Subset D-Lists from D-Cube Data

This example shows how to maintain a D-List hierarchy from data in a D-Cube in the format shown below. For example, suppose you have a long list of cities, but you want to create and maintain a subset list that contains just the European cities. After you have set it up, the D-List can be updated very simply from the source D-Cube data by selecting Update from the D-Cube menu.

Steps
1. Open the D-List containing the European cities. Because you cannot have a D-List with no items, you must have at least one item in this list to begin with. 2. Select Options from the D-List menu and click the Import Link tab. 3. In the Import From box, select D-Cube. 4. Select Update from the Import Mode list, then select the Remove Obsolete Items check box. 5. Select Hierarchical from the Location/Sort Option list. 6. Under D-Cube Data Import, click the button to browse for the D-Cube to use as a source table. You must specify a selection and orientation that opens it. 7. At the first selection screen click the slice. Ensure Cities is set as rows, and city hierarchy set as columns. 8. Do not make a specific selection on the Cities dimension (rows). This means that all rows will be looked at, including ones inserted at a future date. 9. Click the second tab and select the column or columns that contain the hierarchy. These are the columns containing the parent or grand-parent names. Within certain limitations, any number of hierarchy levels are allowed. 10. In the Select attribute box, click the first column (E.g. Cities) and select Item name. 11. In the Select attribute box, click the second column and select Parent. If there are more hierarchy levels, repeat this process by highlighting each column in turn and selecting Parent2, Parent3, and so on. 12. To ensure that only the items with a parent are imported, select the Suppress Zero Rows check box, and then click OK. 13. Select Update from the D-List menu. The new items will be imported into the D-List. 14. Save the D-List. The D-List can now be updated very simply at a later date by selecting Update from the D-Cube menu. This will take account of changes to the hierarchical data in the source D-Cube and update the target D-List appropriately.

138 Analyst

Chapter 7: D-Lists

Manage D-Lists
Management of D-Lists occurs in the library. You can copy, rename, print details, see where a D-List is used, and see what other objects the D-List is dependant on.

Rename/Move a D-List
Before you rename a D-List, ensure the list and all D-Cubes using it are closed.

Steps
1. From the File menu, click Library, D-Lists. 2. Select the D-List and move it to the bottom with the down arrow button. 3. Click the Rename/Move button. 4. Type the new name. Note: You also can move D-Lists to a different library. To move the D-List, select a new library from the Target Library list. 5. Click OK.

<< Move
Click << Move to deselect highlighted items in the D-List Selection dialog box. It removes selected items from the Items Included list and moves them to the Items Available list.

Delete a D-List
You can delete D-Lists only if they are not used by another object, and they are not active or open.

Steps
1. From the File menu, click Library, D-Lists. 2. Select the D-List and move it to the bottom with the down arrow button. 3. Click the Delete button. 4. If you are not allowed to delete a D-List, you can check to see its usage by clicking the Show objects that the selected object(s) is used by (p. 140) button. You must delete the D-Cubes and other objects that use the D-List, or amend them to use a different D-List, before you can delete the D-List.

User Guide 139

Chapter 7: D-Lists

Search for a D-List

You can search for specific D-Lists within a Library by using a filter, or by typing the D-List name.

Steps
1. From the File menu, click Library, D-Lists. 2. From the drop-down box, select a library. 3. Click the Filter button to limit the choice of D-Lists shown. For example, Filter = P* shows anything beginning with P. Alternatively, you can search for a specific name by clicking the Binoculars button and typing the name to search for.

Show a D-List's Dependants

Occasionally, a D-List is dependent on other objects. For example, a D-List might use a saved format named Format-A to set the numeric format of one of its items. Format-A would be a dependant of the D-List.

Steps
1. From the File menu, click Library, D-Lists. 2. Select the D-List. 3. Click the Show objects that the selected object(s) is using button.

Show a D-List's Precedents

A D-List can be used in several D-Cubes. It also can be used in D-Links or even be used in another D-List. The objects (such as D-Cubes or D-Links) that use a D-List are known as its precedents. For example, a D-Cube might be a precedent of a D-List.

Steps
1. From the File menu, click Library, D-Lists. 2. Select the desired D-List. 3. Click the Show objects that the selected object(s) is used by button to see where the D-List is used.

140 Analyst

Chapter 7: D-Lists

Upgrade Pipe Symbols in D-List Item Names

D-lists created prior to Cognos Planning 7.3 with item names containing a pipe symbol (|) may not appears correctly in the D-list editor. Pipe symbols in D-lists created in older versions of Analyst will continue to split long column names.

Steps
1. From the File menu, click Library, D-Lists. 2. Select the D-List and move it to the bottom with the down arrow button. 3. Right-click the D-List and select Upgrade Pipe symbols in D-List item names.

Unique Names
A D-List item may consist of a unique code and name, which makes it easier to match items, especially for data imported from other sources.

Edit Unique Names

Steps
1. Open a D-List. 2. From the D-List menu, click Options, Unique names tab. 3. To remove the column breaks defining unique names, right-click both the starting and ending positions. 4. To redefine the starting and ending positions, drag an existing column break. Note: The Reset button resets the settings to the last saved version.

Define the Unique Part of a D-List Item

When importing D-List items into a D-List on a regular basis, it often is useful to define which part of a D-List item contains a unique code. This lets you test whether it is a genuinely new item or only a slightly different spelling of the description. The unique portion of the D-List item is case sensitive and takes into account leading and trailing spaces. After you set the unique part of a D-List item you cannot type, paste, or import any duplicate items using a D-Link beginning with that code. For example, a typical product code consists of a code followed by a description such as P03 Camping Gear (P03 is the code, Camping Gear is the description). If the following month you are updating the list of product codes and an item named P03 Camping Gear displays, the program recognizes the code (P03). If you are updating the D-List, you can use Append mode to leave the existing description intact, or use Update mode to use the new spelling, thereby preventing duplication of the same product.

User Guide 141

Chapter 7: D-Lists

Total and Subtotal

Be cautious of items beginning with the word, Total. When the unique part of the D-List is defined as the first four or five characters, the word Total is treated the same way as any other code consisting of five characters. If more than one item starts with the word Total the program indicates that this is a duplicate code and prompts you to delete duplicates. If you receive a message telling you that if you continue, items will be removed and asks if you want to continue, click No. You can then go back and rename the totals by assigning unique codes to them.

Steps
1. Open the appropriate D-List. 2. From the D-List menu, click Options, Unique names tab. 3. Look at the Unique Names page of the D-List Options dialog box. To mark the start of the unique part, click once in the text box. To mark the end, click again. To remove line breaks, right-click the appropriate break. - or In the Unique Range box, specify the unique range by entering beginning and ending numbers. 4. Usually, the unique part consists of a code, but it could be the entire description. If this is the case, click Select All, OK. 5. From the File menu, click Save.

Manually Reorder D-List Items

You can choose the order for items in a D-List by manually reordering the D-List. Before reordering, you can search for items based on a character match. Click Search and then type the name of the item to select. Wildcard characters are allowed. Use a question mark (?) for a single character and an asterisk (*) for a series of characters. To use the Search feature, follow these guidelines: Wildcard characters of * and ? are allowed in the filter. Use a question mark (?) to represent any single character. Use the multiplication symbol (*) to represent any series of characters. Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters.

142 Analyst

Chapter 7: D-Lists The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria.

Steps
1. Choose whether you are reordering from a D-List or from a D-Cube: If reordering from a D-List, from the D-List menu, select Reorder, Manual If reordering from a D-Cube, right-click a D-List dimension and choose Re-Order Items from the list.

2. In the Reorder Itemsdialog box, in the Items Included area, select the items you want to reorder and use the arrow keys to move the selected item up or down to move to the top or bottom. Tip: Non adjacent items can be grouped together: Select the items to group. While holding CTRL, click to select non adjacent items. Group all selected items together at the top or bottom using the arrow keys. You now can position the group of items using the arrow keys to move up or down. 3. When you finish reordering items, click OK. 4. From the File menu, click Save.

Sort D-List Items

You can sort D-List items based on one of the hierarchical sort orders available.

Steps
1. Open the D-List you want to sort. 2. From the D-List menu, select Reorder and choose the sort order you want. A summary of the sort orders is given below.

Sort Order
Normal Alphabetical Rev Alphabetical

Explanation
The sort order saved on the D-List. Alphanumeric abc123. Reverse alphanumeric 321cba.

User Guide 143

Chapter 7: D-Lists

Sort Order
Totals After/Calc

Explanation
A hierarchical sort, with subtotals below their children, sorted within each subtotal according to the order found in the calculation formulas. The grand total is at the bottom. In the event of multiple overlapping hierarchies, items outside the main hierarchy appear at the bottom, below the grand total of the main hierarchy. The main hierarchy is chosen as the hierarchy below the first grand total in the list. A hierarchical sort, starting with the grand total and then each subtotal appearing above its children. In the event of multiple overlapping hierarchies, items outside the main hierarchy appear at the bottom, below the grand total of the main hierarchy. Same as Totals Below, but sort alphabetically within each subtotal. Same as Totals Above, but sort alphabetically within each subtotal. Same as Totals Below, but sort reverse alphabetically within each subtotal. Same as Totals Above, but sort reverse alphabetically within each subtotal. Same as Totals Below, but uses the current D-list order within each subtotal. Same as Totals Above, but uses the current D-list order within each subtotal.

Totals Before/Calc

Totals After/A-Z Totals Before/A-Z Totals After/Z-A

Totals Before/Z-A

Totals After/None

Totals Before/None

View/Edit Summary Information on a D-List

Steps
1. Open the D-List. 2. From the File menu, click Summary Info. 3. On the general information page, you can add a description and write notes about the D-List. The DOS file name is available only to the system administrator. 4. To see what objects a D-List is using, click the Objects used tab. 5. To see D-Cubes and other objects that use a D-List, click the Usage page.

144 Analyst

Chapter 7: D-Lists 6. Click OK. 7. If you changed the description or the owner's note, save the D-List.

Add Sub Headings to Reports

You can insert subheadings in reports, but you see them in Manager only, not in Analyst. You can assign subheadings to one or more D-List items such that when the item is selected as a row label in a report, the subheading displays above it.

Steps
1. From the File menu, select Open and then click D-List. 2. From the D-List menu, click Options. 3. Click the Subheaders tab. 4. On the Subheaders page, click New and then type the header text in the Header Text box. 5. In the Alignment box, select the position of the text: Select Left for left-justified text. Select Center for centered text. Select Right for right-justified text.

6. In the Fonts section: Select Common font size for one font size and specify the size in the Font size list. Select Multiple font sizes for more than one font size; then click Edit font size to specify. Click OK.

7. In the Select items to include in current header box, click the items you want to go into the subheading from the Items Available list. Whenever any of these items display as row labels in a report, the subheading displays above the first item. 8. To move the selected items to the Items Included list, click Move>>. 9. Click OK to return to the D-List options screen. 10. Click OK to return to the D-List. 11. From the File menu, click Save. Note: In normal use, the subheader displays in reports but not in the D-Cube.

User Guide 145

Chapter 7: D-Lists

Set D-List Colors

It is sometimes useful to group families of D-Lists by assigning them the same color. This can serve as a memory jogger when working with D-Lists. Most D-Lists belong to one of these categories. In general, when you set up D-Links to copy data between D-Cubes, you should map the links between D-Lists of the same family.

Steps
1. Open a D-List. 2. Click the small color box to the top left of the D-List. 3. Select a color from the palette. The recommended color conventions are listed below:

Types of D-List
Account codes, Profit and Loss items, balance sheet, other calculation D-Lists

Color
White

Divisions, regions, geographical, cost centers, personnel names Green Products, brands, services Customers Days, months, weeks, quarters, years, time Versions, actual/budget/variance Purple Blue Cyan Yellow

146 Analyst

Chapter 8: D-Cubes
A D-Cube is a store of data within a model. It is multi-dimensional and contains rows, columns and any number of pages. The D-Lists form the dimensions of the cube. Unlike a spreadsheet, D-Cubes can be sliced so that any pair of dimensions can comprise the rows and columns while additional dimensions comprise the pages. Cognos Planning - Analyst can handle any number of dimensions, the only practical limitation being the memory in your PC, but typically a D-Cube will contain no more than 5 or 6 dimensions. A D-Cube must contain at least two D-Lists (similar to a flat spreadsheet). Alternatively, a D-Cube can have three D-Lists, in which case it resembles a three-dimensional worksheet consisting of several flat sheets stacked behind one another. A four or five-dimensional D-Cube can be considered the same as a cross between a three-dimensional spreadsheet and a set of query reports from a relational database. A typical four-dimensional D-Cube would contain the D-Lists: P&L, Divisions, Months, and Variance. Note: Format and Formula priority: When you create a D-Cube, it is best to choose the D-Lists in a set order to overcome any priority conflicts on formulas at a later date. In general, select D-Lists with the most calculations first, particularly when the calculations use IF...Then...ELSE logical operators. Select the aggregation D-Lists next (divisions, customers, products) then the timescale D-Lists. Finish with the versions D-List. The default formula priority is given to the later D-List in a D-Cube, whereas format priority is given to the earlier D-List.

Size Limitations
There is no software limitation on the number of cells contained in a D-Cube, but there is a hardware limitation that depends on the memory in a computer. To determine the size limitation, the number of cells is determined by multiplying the number of rows by the number of columns by the number of pages. To put it another way, the number of cells is the product of the number of D-List items contained in each D-List. Size = (no. items D-List 1)* (no. items D-List 2)* (no. items D-List 3)* . . . *(no. items D-List n). Size limitations vary greatly depending on the memory in your computer. D-Cubes containing long D-Lists of 500 items consume more memory than similarly sized D-Cubes containing D-Lists of 100 items. In general, size limitations become apparent in D-Cubes of four or more dimensions. If you have a three-dimensional D-Cube of 400 pages, adding another dimension of 20 items increases the memory usage twenty-fold. In other words, you increase the data held from 400 pages to 8000 pages. Adding a fifth dimension of 20 items increases the memory usage by twenty-fold again to 160,000 pages of data. In practice, this memory limitation is overcome by creating a series of well-populated D-Cubes of three or four dimensions rather than one sparsely populated D-Cube of five dimensions.

User Guide 147

Chapter 8: D-Cubes

Interrupt a Calculation
If a calculation is taking a long time, you can interrupt it. If you interrupt a calculation and you have Undo enabled, and the memory limits are set high enough to contain a full copy of the current D-Cube data in memory, the D-Cube editor will revert to the latest D-Cube version available in memory. If Undo is disabled when you interrupt a calculation, all current changes will be discarded and the D-Cube editor will revert to the last saved version.

Steps
1. To interrupt a calculation, click the red cross that appears in the main toolbar. This button appears only when it is safe to stop calculating. 2. To ensure the integrity of the data after interrupting a calculation when Undo is turned off, from the File menu, click Reset to return to the saved version.

Set or Clear Audit Trails

You may set an audit trail on a D-Cube that records the changes for each session. When viewing the audit trail of a cells in a D-Cube, it shows the changes for the last session in which the cell was affected. This is not necessarily the latest session, simply the last session in which the number was altered by over-typing, executing a calculation, breakback, D-Link, or other method. A session is defined as a period between saves.

Steps
1. Close all objects so that you start from a blank screen. 2. From the File menu, click Library, D-Cubes. 3. Click the D-Cubes you wish to monitor, and then click the down arrow. 4. Choose whether to set or clear the audit: To set the audit, right-click the D-Cubes, select Set Audit from the list, and then click OK. The status of the audit trail shows if the object is currently being audited. To clear the audit, right-click the D-Cube, select Clear Audit from the list and then click OK. This clears the slate entirely. It will discard all old audit information and prevent any future audit trail from being recorded until you choose Set Audit once more. 5. Close the D-Cube Library window. The program will now begin to record any changes to that object.

148 Analyst

Chapter 8: D-Cubes

View the Audit Trail of a Cell Within a D-Cube

To track changes on a more granular level, you can view the audit trail of a cell within a D-Cube.

Steps
1. Right-click a cell and select Audit. This will show the last session in which the cell was affected, not necessarily the latest session. 2. (Optional) You may browse backwards or forwards through the audit records using the Previous and Next buttons. Each record contains a list of actions between saves. 3. If you want to search for a text string within an audit record, from the File menu, click Find, and then type the text to search for. Clicking Find Next or pressing the F3 key jumps to the next occurrence of the text string within the current page. 4. If you want to print all records, from the File menu, click Print. Tip: To preview the records before printing them, from the File menu, click Print Preview.

Breakback
Breakback answers what-if problems by changing the value of any number of variables to make a formula equal to a value you specify. With breakback, you set a target for a formula, and the variables that make up that formula are changed according to the rules you specify. In the default breakback mode, totals are split pro rata according to the original values contained in the variables that make up the formula. Zeros remain at zero with one exception: if all the variables in a formula are initially zero, the total is split equally down the hierarchy.

Default Rules for Breakback

The fundamental default rule for breakback is that changes are allocated to variables in a formula in direct proportion to their initial values. In other words, the more you have initially the more you get. This is what the program does in the absence of any other rules you might set. Breakback will not work over built in functions or conditional formulas. In the event of a profile that contains mixtures of zeros and values, zeros remain at zero, the remainder being allocated pro rata across the other variables. For formulas with a mixture of additions and subtractions, the default rule increases the items that are additions and decreases the items that are subtractions by an amount proportional to the initial values. For example, suppose a D-List contains the formula: Consider a simple example containing straight addition of detail items. A simple D-List contains four detail items and a total. The formula for the total is:

User Guide 149

Chapter 8: D-Cubes Company Total = North + South + East + West Likewise, a Periods D-List is also used where Period 1 + Period 2 + . . . + Period 12 = FULL YEAR If you type data in the Company Total cell, breakback allocates the total pro rata according to an initial profile or weighting. This profile is determined by the value of the original items held in the detail items. For example, if you have a D-Cube with four divisions and a Company Total, with each division having the number 25 entered in it, the formula would allocate 25 percent of any changes in the total to each variable. If you then typed 1000 in the Company Total cell and pressed Enter, the four divisions would receive 25 percent of 1000, or 250 in each division. The profile need not be a percentage. For example, suppose each division were given an equal initial weighting of 1, then the result would split equally. If you type 1000 in the Company Total cell and press Enter, the result would still be 250 in each division. The same result could be achieved by giving an initial profile of all zeros. Before the breakback, everything reads zero; after entering a number in the Company Total cell, every item receives an equal allocation. Profit = Sales - Costs Initially Sales =60 Costs =40 So Profit = 20 The effect of increasing Profit from 20 to 30 increases Sales by six and decreases Costs by four in direct proportion to their initial values. The percentage change of each variable is determined by the relative size of the initial values. The effect of breakback on formulas containing multiplication is slightly more complex, but again, the pro rata rule applies. For example, if you have the formula: Sales = Units * Price If Sales are doubled, both Units and Price increase by the same percentage with respect to their original values. In this case, both will increase by the square root of 2. The effect of breakback on formulas containing division is similar to multiplication. The effect of an increase in the result is to increase the numerator by the same percentage as the denominator. Again, the pro rata rule applies. For example, if you have the formula: %Margin = (Margin / Sales) * 100 If % Margin is increased, Margin goes up by the same percentage as Sales go down. This keeps both variables in proportion to their original values. In fact, if % Margin doubles, then Margin goes up by a factor of the square root of two whereas Sales go down by a factor of the square root of two. In this last case, it would be better to hold or increase Sales before changing %Margin. The computer lacks the intelligence to know whether an increase in %Margin is best achieved by an increase in Sales, a reduction in Costs, or some mixture of the two.

150 Analyst

Chapter 8: D-Cubes

Breakback vs. the Solve Facilities in Spreadsheets

Breakback is similar to the Solve and Backsolve facilities in certain spreadsheets, but is far more powerful. Breakback can cope with any number of variables or any number of formula targets, it works across multiple dimensions and down multiple formula hierarchies, and the rules can be set in advance to decide which groups of variables to hold, to increase by a percentage, or to allow to float freely. If you enter a number in a total cell in a spreadsheet, it would come up with an error. By contrast, breakback begins automatically whenever you enter or copy a number into a formula cell.

Use Breakback to Set Global Targets

You can set targets across more than one dimension. In fact, you can enter a grand total in the bottom-right corner on the final page of a D-Cube, and the details are altered across all rows, columns, and pages.

Steps
1. Create or open the D-Cube to which you want to apply the breakback. 2. Set the profile. Generally, this is done by copying numbers in using a D-Link from the D-Cube where the profile is stored. 3. Enter the target in the total cell. Typically, this is done by copying numbers in using a D-Link from the D-Cube where the targets are stored. 4. Press Enter. The changes are split pro rata across the detail items using the profile as a guide.

Holds and Breakback

Applying a hold to a cell freezes its value against changes induced by breaking back a formula total. Breakback allocates any changes pro rata to the other variables making up the formula, leaving the held cell unchanged. Note: If any holds are placed on a subtotal within a D-Cube, then a breakback will automatically be performed. Only use a hold on a subtotal when necessary and when model design has been geared for holding subtotals.

Why Data Can Change Despite Being Held

Held cells are not write-protected. This means that you can type data directly into a held cell. A held cell is held only against breakback, it is not write-protected against data entry, nor is it invulnerable to having data copied into it using a D-Link or pasted into it using the clipboard. A second example in which held cells can change is when you have not given the program enough freedom to calculate. In these cases, data is changed in held cells despite the hold being applied. User Guide 151

Chapter 8: D-Cubes For example, suppose you were to apply a hold to all four divisions and then hold the COMPANY TOTAL cell as well. The program has no freedom at all. Total Company = North + South + East + West Were you to enter data in the North division without releasing any of the other divisions or the total, the Total Company cell would change despite being held. In this case, you would not be giving freedom to the program. The forward calculation would have priority over the hold on the total. If you were to enter data in the Total Company cell without releasing any holds, the total would not change. In this case, the holds on the detail items have priority over the breakback calculation. As a rule of thumb, you should release all holds after each breakback operation.

Apply a Hold
To apply a hold, use D-Cube commands (p. 173).

Remove a Hold
To remove a hold, use the D-Cube Release command (p. 173).

Example - Hold Cells

Consider a simple example in which the North cell is held by typing hold directly into the cell. The formula for the total is: COMPANY TOTAL = North + South + East + West If you enter data in the Total Company cell, breakback allocates the total pro rata according to an initial profile or weighting. However, because the North division is held, it is invulnerable to breakback and stays unchanged. Thus, the changes are allocated pro rata across the South, East, and West divisions. If each cell initially contained the value 150 with a total of 600 and you then input 750 in the total cell, the increase of 150 will be shared between South, East and West equally. Since their initial values were equal, these will all increase to 200 while North will remain unchanged. You can type or copy data using operators at the same time you apply holds.

Using Breakback with Integer Arithmetic

Breakback can be set to integer mode or decimal mode. The default mode is set to decimal mode. However, you can set breakback to integer mode to round all numbers to integers whenever a breakback is triggered. Breakback in Integer mode can be used for applications where decimals are not logical, such as for headcount allocations or for rounding data for presentation purposes where a numeric format (or scaling) is insufficient.

Rounding Errors
Frequently you hear people claim that spreadsheets do not add correctly or that they contain rounding errors. This is a false allegation against spreadsheets that calculate to decimal places. The rounding errors that occur are so minimal as to be insignificant. However, it is not a trivial issue.

152 Analyst

Chapter 8: D-Cubes There are cases where numbers displayed to too few decimal places do not seem to add correctly (see the example that follows). Many hours have been spent using spreadsheet macros and rounding facilities trying to overcome this apparent anomaly. Analyst offers a solution to rounding anomalies by using breakback in integer mode. It should, however, be used with caution. If breakback is set to integer mode, the underlying detail numbers are changed. Although it is useful for presentation purposes, if you are sending the data to be consolidated elsewhere, it is generally better to use decimal mode so that the integrity of the data is maintained. The best solution is to produce reports with numbers formatted to one more decimal place than you have been asked for. In the example below, the sum is 1.333+1.333+1.333+1.000=4.999. However, if you set the decimal places to zero, the sum reads 1+1+1+1=5. This is upsetting because it seems to contravene the rules of mathematics. Actually, it is the mathematically correct solution because each number is rounded correctly, but try telling that to the boss! Breakback in decimal mode does not round the variables at all. Breakback in integer mode rounds the variables to the nearest integer. By rounding to integers, the sum 2+1+1+1=5 seems to add correctly even when no decimal places are shown. This can be useful for presentation purposes. However, a break back must be triggered for the rounding to occur.

Set Breakback to Integer or Decimal Mode

Breakback can be set to Integer mode or Decimal mode. The default mode is set to Decimal. However, you can set breakback to Integer mode to round all numbers to integers whenever a breakback is triggered. Breakback is similar to Solve and Backsolve facilities in certain spreadsheets, but is far more powerful. Do not use Integer mode for models used to create Contributor applications.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Options, Break-Back tab. 3. In the Options dialog box, do the following: If you do not require rounding when performing breakback, select Decimal. If you require rounding integers when performing breakback, select Integer.

4. Click OK.

Set a Target Using Breakback

Steps
1. Open the appropriate D-Cube.

User Guide 153

Chapter 8: D-Cubes 2. Enter the profile into the detail items. Typical profiles include a seasonality pattern, last year's actual results, a headcount, or other cost driver. Alternatively, enter the absolute numbers and tweak the total using breakback. 3. Optional: Apply any holds or other commands to the detail items. 4. Enter the data into the formula cells, and press Enter. Breakback is triggered automatically, allocating the changes pro rata to the variables that make up the formula.

Create D-Cubes
Use a D-Cube to enter data, perform multidimensional analysis, and calculate and collect data. You use D-Lists to define the dimensions for a D-Cube. The D-Lists are used to perform calculations, control labels, and format data entry. Add D-Lists in order of category number to maintain the correct calculation precedence.

Order of D-List Selection

When selecting D-Lists for a D-Cube, the order of selection does not affect which D-Lists end up as rows or columns. In practice, the default setting designates the longest D-List as row labels and any timescale D-List as column labels. This can be changed by transposing rows, columns, and pages as needed. However, the order is significant when it comes to the priority of calculations. At the intersection of two totals contained in separate D-Lists, the program must distinguish between using a formula in only one D-List. For straight addition or subtraction, it is irrelevant which formula is used because both calculations produce the same result. For multiplication or division, the order should not matter provided the percentages, ratios, or per unit items have been set as weighted averages. However, for logical operators (IF THEN ELSE), the priority is significant. When there are two formulas of equal priority, precedence goes to the D-List chosen last during the creation of the D-Cube. Consequently, any D-List using a logical formula should be selected first to give it a lower priority. This ensures that the whole is equal to the sum of its parts when aggregating other dimensions. For formulas, the priority goes to the later D-List unless overridden by priority settings on individual D-List formulas. These can be set to High, Medium, or Low. The default priority is Medium. As a general rule, choose D-Lists in the following order: Calculation D-Lists such as P&L, Balance sheet D-Lists. Aggregation D-Lists such as products, customers, divisions, cost-centers, regions, or subsidiaries. Time D-Lists such as months, quarters, or years. Only one timescale D-List can be chosen in each D-Cube.

154 Analyst

Chapter 8: D-Cubes Control D-Lists such as Actual/Budget/Variance.

If the order is wrong, you can change it later from the D-Cube menu, clicking Dimensions, Reorder.

Format Priority
Format priority in a D-Cube cell is determined by the order in which you include D-Lists in the D-Cube. The first D-List in the D-Cube takes precedence.

Example - Prioritizing Formats

You have P&L and Months D-Lists. The P&L D-List contains an item, Margin %, formatted with a percent sign and zero decimal places. The Months D-List contains an item, Current Month, formatted to two decimal places. Now you build a D-Cube using these two D-Lists inserting P&L before Months. The Margin %, Current Month cell is formatted with a percent sign and zero decimal places. This is because the P&L D-List is the first D-List in the D-Cube and has format priority. Note: All formats available for individual D-List items also can be set for a D-Cube as a whole. Formats set at the D-List item level override those set at the D-Cube level. In other words, a format set in a D-Cube is active only in D-List items that have no format attribute set.

Steps to create a D-Cube

1. From the File menu, click New, D-Cube. 2. In the Create New D-Cube dialog box, select the D-Lists to include in the D-Cube. Then move each D-List to the Objects Selected box by clicking the down arrow button. You can preview any of the D-Lists you are using to build the D-Cube. Simply right-click the D-List item name. You can re-order the dimensions by using the four arrow keys located above the Cancel button. As a rule of thumb, select the D-List with the most complex calculations first, to avoid problems with priorities of calculations. Note: Holding Ctrl and clicking D-Lists lets you select multiple nonadjacent items. 3. Click OK. 4. Name the D-Cube. Note: The D-Cube name is case sensitive and must be unique within a library. 5. Click OK. 6. In the Selection dialog box, click OK to open the entire D-Cube.

User Guide 155

Chapter 8: D-Cubes Clicking OK without selecting any items in the Selection dialog box selects all items. Alternatively, you can hide rows, columns, and pages at this stage by selecting only the items you want to display.

Steps to work with a limited selection

1. In the Items available list, select the items. 2. To move the items to the Items included list, click Move>>. 3. Repeat steps 1 through 3 with the other D-Lists (if necessary). 4. Click OK. The D-Cube appears, ready for data entry.

Open D-Cubes
Open a D-Cube to populate it with real-time data and begin your analysis. You can also open a D-Cube to add some test data before the actual budget data becomes available. You can re-orient the D-Cube so that certain dimensions fall on rows, columns, and pages.

Steps
1. From the File menu, click Open, D-Cube. 2. Click the name of the D-Cube you want to open. You can choose to open a D-Cube from another library if you have access rights. 3. If you choose to open a D-Cube from another library, click the library name to select it, and then select a D-Cube name. 4. Click OK. 5. Choose the mode in which you want to open the D-Cube. Click Full to open the entire D-Cube. The full cell count of the cube appears on this screen whichever option you choose. Click Saved Selection to open a previously saved selection of rows, columns, and pages. Then choose the name of the selection. Click Edit Selection to work on a limited number of rows, columns, and pages by selecting some and hiding others.

Note: If you select Edit Selection, you must move items you want to display to the Items Included list. Select the items you want and then click Move>> to move them to the Items Included List. Repeat for each D-List by clicking the D-List tabs. Leaving the selections blank selects everything. 6. Click OK. The selected rows, columns, and pages of the D-Cube appear. 156 Analyst

Chapter 8: D-Cubes 7. To close the cube, from the File menu, click Close. If you have not saved the D-Cube, you are prompted to do so. 8. To save before closing, click Yes. If two views of the same D-Cube are open, they can be closed one at a time. However, if the selections are different, you must save the changed data when prompted.

Open Multiple D-Cubes

It is possible to have several D-Cubes open at the same time.

Steps
1. From the File menu, click Library, D-Cubes. 2. Choose the correct library from the selection box in the top left hand corner 3. Highlight the cubes you wish to open and click the down arrow to move them to the lower pane 4. Choose a different library and select more cubes, if necessary. 5. From the central toolbar, click the Open objects icon. The active D-Cube is indicated by the blue highlighted title bar. 6. To activate another D-Cube, click anywhere in the window. Tip: To change from one window to another, press Ctrl+TAB.

Expand a Subtotal
Clicking Expand in the Selection dialog box selects the variables that go into a formula. It can be used to expand selected totals in either the Items Available list or the Items Included list. By repeatedly clicking Expand, further levels of the formula hierarchy can be highlighted. It can be used to expand more than one subtotal at the same time. Note: Clicking Expand applies the selection, but does not specify whether the selected items are to be included or not. After clicking Expand the selected items must be moved to the Items included list or the Items available list by clicking Move>>.

View Multiple Slices of a D-Cube in Separate Windows

You can change the perspective of a D-Cube by slicing and dicing the cube. D-Cubes can be sliced so that any pair of dimensions can comprise the rows and columns while additional dimensions comprise the pages.

User Guide 157

Chapter 8: D-Cubes Exchanging the position of D-Lists does not affect the order of the D-List in a D-Cube in terms of calculation order. It changes only the way the D-Cube is displayed.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Selections, New Slice. A new window appears containing another view of the same D-Cube. This can be sliced independently of the first view. The active slice is indicated by the blue highlight at the top of each window. 3. If you want to change the position of the windows, from the Window menu, click Cascade, Tile Horizontally, or Tile Vertically. 4. If you want to move between windows, from the Window menu, select the relevant window. To change from one window to another, press Ctrl+Tab. 5. To close a window, make the slice you want to close into the active window, and then from the File menu, click Close.

D-Cube Data Allocations

A D-Cube data allocation uses a D-Cube as a source for allocating items from a source dimension to a target dimension within a D-Link. If you specify a selection and slice that a D-Link cannot interpret as an allocation table, you will see the "Nothing to Transfer" message when the D-Link is run. You will have to return to the D-Link and specify the selection and slice from the allocation D-Cube again. If the D-Link can interpret your selection and slice as an allocation table, but the allocation table does not match the source and/or target items, you will see a 'No items match' message. A D-Cube used in this way will contain columns of D-List formatted data. The D-Cube can have multiple columns and multiple pages but the slice used as the data allocation must consist of a single page and a single column. The column must be D-list formatted. Thus different slices of the same cube may be used in the same or many different D-Links.

Example
If you have a D-Cube that has a D-Cube data allocation that allocates cost centers to both divisions and managers as follows:

Divisions
Cost Center 1 Cost Center 2 USA Germany

Manager
Manager 2 Manager 3

158 Analyst

Chapter 8: D-Cubes

Divisions
Cost Center 3 Cost Center 4 Cost Center 5 Cost Center 6 Cost Center 7 Cost Center 8 Cost Center 9 Cost Center 10 Cost Center Total France U.K. USA Germany France U.K. USA Germany

Manager
Manager 1 Manager 1 Manager 2 Manager 4 Manager 4 Manager 1 Manager 3 Manager 3

Cost Center 1 is located in USA and is managed by Manager 2. Similarly, Cost Center 2 is located in Germany and is managed by Manager 3. In this manner, the remaining cost centers are each located in various countries (USA, Germany, England, or France) and managed by various managers (Manager 1 through Manager 4). Note that one manager can be responsible for multiple cost centers in different cities.

Enter Data
When you enter data in a D-Cube, the color of the data indicates whether the data is saved, a working copy, or not calculated. If you make a mistake while entering data, you can reset a cell to its original or saved value. By default, the Undo facility is not turned on. For large D-Cubes, turning on the Undo can affect performance, so the Reset command can be used as a viable alternative.

Enter Data into Individual Cells of a D-Cube

Data can be entered in the D-Cube by typing directly into an individual cell. After typing a number, press Enter to calculate or ESC to cancel. Column widths expand automatically to accommodate the largest number on the page you are working on. As a rule, type numbers in the blue data entry cells. Numbers that have just been entered display in green, but do not calculate until the enter key is pressed. After calculation takes place, the numbers change to red.

User Guide 159

Chapter 8: D-Cubes Entering numbers in the black formula cells triggers the breakback function. This is the equivalent to setting a target result and directing the program to break back pro rata with numbers that will meet that target. If you have changed a formula in a D-List, numbers are not recalculated in the D-Cube until you implement the changes.

Color Conventions for Data

Data that has been entered is not calculated until you press ENTER. This means you can make changes to the data without processing the changes by not pressing ENTER. Cognos Planning - Analyst uses color conventions to indicate the type of data in a cell. A summary of these conventions is given below.

Cell Type
Normal Protected Locked Held Protected and Held Protected and Locked Locked and Held

Background Color
White Yellow Light gray Light turquoise Light green Light gray Dark gray

Cell Type
Typed, but not calculated data changes Changed detail item Changed formula result Unchanged detail item Unchanged formula result

Text Color
Green Pink Red Blue Black

160 Analyst

Chapter 8: D-Cubes

View a Formula
You can view a formula to better understand complex calculations used in the D-CUbe.

Step
Move the cursor to a black or red formula cell and press F7. Alternatively, from theD-Cube menu, click Show Formulae. The formula currently being used appears first.

View the Origin of a Detail Cell

You can drill on D-Cube data that was imported by a D-Link, provided the D-Link was saved. Drilling shows the original source data regardless of its origin.

Step
To view the origin of a detail cell, click the cell, and then click the Drill Down button. Tip: Alternatively, you can press F9. If the cell is a target of a D-Link then the data which would be transferred to the cell by the D-Link opens in a separate window. If the cell is the target of multiple D-Links then multiple windows will open. The data in the cell may differ from the source data shown depending on which D-Link was the last to run and whether data has subsequently been entered into the cell. To track changes to a cell, use an audit trail (p. 148).

Edit D-Cubes
You can edit D-Cubes by copying data from within the cube or external sources outside the cube, suppressing zero rows, columns, or pages, and annotating cells,

Copy a Range on the Same Page

You can copy a range of cells from one area of the page to another.

Steps
1. Open a D-Cube. 2. Select the range you want to copy from the source D-Cube. 3. From the Edit menu, click Copy. 4. Select the range to which you want to paste the data.

User Guide 161

Chapter 8: D-Cubes You can paste single columns into selected multiple columns. If the range of the target area is smaller than the range copied to the clipboard, only the earlier rows and columns are pasted in. 5. From the Edit menu, click Paste. The data is pasted in the cells and displays in green to indicate that the numbers have not yet been entered. 6. To calculate, click the page once and press Enter.

Copy Ranges in a D-Cube from Page to Page

The recommended method for copying data from page to page is to use an internal D-Link (p. 215). This allows changes of a more global nature rather than copying to and from the clipboard. It also permits a single page to be copied to multiple pages in a single operation, rather than using multiple copy and paste commands. In fact, it allows any range, adjacent to or not, to be copied to any other range.

Steps
1. Open the D-Cube. 2. From the D-Cube menu, click D-Links, Internal. 3. Click the yellow arrow connecting the relevant D-Lists. The default color of the arrow is yellow to indicate that items are matched using a match descriptions pairing (p. 233). 4. Select Change to allocate. This changes the yellow arrow to a green and red arrow, indicating that items are matched using a local allocation table pairing. An allocation table allows you to specify any correspondence of source and target items. You can mix one-to-one, many-to-one, and one-to-many allocations in one allocation table. 5. Select the items to copy. 6. On the Source side, click the D-List item you want to copy. 7. On the Target side, click the relevant D-List item. The allocation table in the center shows how the source and target ranges correspond. Note: If you make a mistake, select the line in the allocation table and press Delete (this action deletes a single line of the table). 8. Repeat with the other items. 9. To copy the range by running the internal D-Link, click the D-Link menu, and then click Execute. Unlike the copy and paste functions, a D-Link calculates in addition to copying, so that numbers display in red to show that they have changed. 162 Analyst

Chapter 8: D-Cubes 10. From the File menu, click Save.

Copy Data Using Operators

Certain copy commands are allowed to help you copy data on the current page. These abbreviations are typed directly into the cell.

Copy the Underlying Value Contained in a Cell Using the Copy Commands
The copy commands operate on numbers on the same level in the calculation hierarchy. A copy command entered in a detail item copies the item to all subsequent details, skipping any formula items. A copy command entered on a formula copies the formula to all other formulas. For example, 4000> entered in quarter1 skips the months, but copies the number 4000 to all subsequent quarters. Then breakback decides how the quarterly value of 4000 is split by month. Copy commands are terminated by any other copy command in their path or by the colon break (:). The colon (:) acts as a break that copies up to, but does not include, the current cell contents. The following copy commands are available:

command
greater than sign (>) less than symbol (<) pipe symbol (|) 'power of' symbol (^)

description
Copies data to the right along the same row. Copies data to the left along the same row. Copies data down the same column. Copies data up the same column.

Enter a Number and Copy it Across and Down Cells at the Same Time
The copy commands can be combined to facilitate data entry. For example, using the greater than sign (>) followed by the pipe symbol (|) tells the program to copy the number across and down the cells. As with all data entry, copy commands are not processed until you press Enter.

Steps
1. In the desired cell, type the sign for the operation required. 2. Press Enter.

Copy from a Spreadsheet to Analyst

You can copy data from a spreadsheet using the Windows clipboard or using a D-Link. For more information about D-Links, see "D-Links" (p. 215). User Guide 163

Chapter 8: D-Cubes We recommend the D-Link method because it provides an audit trail back to the source data, provided the D-Link has been saved and does not rely on the relative position of cells. Instead, it effectively gives each spreadsheet cell a range name that can be directed to the correct cell in the D-Cube. For any large spreadsheet, we recommend a D-Link as the optimal choice. If the spreadsheet uses a series of sections, you can use the Follow On facility in the D-Link to direct the data to the correct page. If it is set up as an ODBC source then a 100-page spreadsheet could be copied in one step rather than 100 separate copy-and-paste steps. To be comprehensive, the copy-and-paste method is shown here, although it cannot be stressed enough that the D-Link method is better in almost every case. If you use the copy and paste method, the position of rows and columns must be identical in both the source spreadsheet and the target D-Cube. This is possible if the D-Lists have been created from the spreadsheet itself. It can be a quick method of copying data between a spreadsheet and a D-Cube; however, ensure that blank rows and columns are eliminated and that the areas to copy from and to match exactly. Note: To avoid the possibility of triggering an unwanted breakback in analyst, you should paste data into detail cells of a D-Cube only.

Steps Using the Copy and Paste Method

1. In the spreadsheet, select the range you want to copy. Exclude row and column labels; select the data only. 2. From the Edit menu, click Copy. 3. Open Analyst and select the range of cells in the D-Cube to which you will paste. 4. From the Edit menu, click Paste to paste the data. It is pasted according to cell position, not according to the range names of the cells.

Insert Lines to Separate Totals from Detail Items

It is possible to insert lines that separate the detail items in a D-List from the totals. Lines can be placed before or after totals. The color, thickness, and style also can be set.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Options, Lines tab. 3. Look at the Lines page and do the following: Click the list to select where to insert lines (separating columns or lines separating rows). Click Before to insert lines before totals. Click After to insert lines after totals. Note: The lines are inserted automatically to separate the formula items from detail items, regardless of the slice of the D-Cube. 164 Analyst

Chapter 8: D-Cubes Click Color and select a color from the list. Enter a line thickness in the Thickness box. Select a line style from the Style box.

4. Click OK. Note: Although the facility to insert blank lines is not really featured in Analyst, there is a slightly ambiguous method of creating them. Insert D-List items containing just the underscore character ( _ ). Then apply a numeric format (p. 112) to the underscore item and select blank if zero (p. 193). As D-List names have to be unique, the number of underscore characters must vary if more than one blank line is inserted.

Edit Undo and Redo

To recover from most errors, press ESCAPE. However, even if you have pressed Enter you can still go back one step at a time using the Undo function. The program lets you go back several steps. The Redo command takes you forward one step at a time. Note: The number of undo and redo steps available are indicated in the menu bar at the bottom of the screen. For example U2 means two steps of undo available. R2 means two steps of redo are available. The Reset button resets the settings you are working on back to the saved version.

Suppress Zero Rows, Columns, or Pages

You may hide blank rows and columns that contain all zeros.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Options. 3. Click the Zeros tab. 4. To hide blank rows, columns or pages, select Suppress Zero Rows, Suppress Zero Columns or Suppress Zero Pages, or any combination of these three options. This will suppress zeros based on the slice. If the Suppress Zero Rows box is selected, zero rows will be hidden no matter which D-List happens to constitute the rows at a given time. Suppress Zero Pages is used to suppress blank pages from being printed or exported to text or ASCII files. 5. Click OK. 6. Save the D-Cube.

User Guide 165

Chapter 8: D-Cubes

Reveal All Zero Suppressed Rows and Columns

Depending on the type of analysis you want to perform, you may want to see all data each time you open a D-Cube, regardless of whether the rows or columns contain zeros.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Options. 3. Click the Zeros tab. 4. Clear the appropriate Suppress Zero Rows, Columns, and Pages check boxes. 5. Ctrl+Click the highlighted items to clear the selection in the Suppress Zero Items for D-List check box. 6. Click OK. 7. Save the D-Cube. Note: Reset Structure resets the zero suppression settings back to the last saved version of the D-Cube.

Change the Column Width or Row Label Width

By default, Analyst sets the width of a column to nine characters. The default for the row labels is five characters.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Options. 3. Click the Widths tab. 4. Set the column width in number of characters. This includes the digits, comma delimiters, decimal point, currency and other suffixes and prefixes. The default is a minimum of nine characters. 5. Click Minimum to use the widths setting as the minimum column width, but allow for expansion as needed to fit the largest number. 6. Click Show Column Labels to show the column labels in full. This will automatically widen each column to fit the label. The default is to truncate the column labels according to the width setting. The Show Column Labels option is not available if the width is set to Exact. 7. Click Exact to use the width setting as an exact column width.

166 Analyst

Chapter 8: D-Cubes This sets all columns to the same width. This looks neat but will not allow for expansion of the columns to fit large numbers. If the width of the largest number exceeds the Exact width setting, then a series of ####### symbols will appear and you must increase the width setting. 8. Set the row Width in number of characters. This includes the digits, comma delimiters, decimal point, currency and other suffixes and prefixes. The default is a minimum of 5 characters for the row labels. 9. Click Minimum to use the row widths setting as the minimum number of characters, but allow for expansion as needed to fit the longest label. 10. Click Exact to use the width setting as an exact row width. 11. Click OK. The width settings may be saved with the D-Cube.

Annotate a Cell
You can attach a note to any cell regardless of its format. This is particularly useful for providing additional information regarding a particular cell.

Steps
1. Open or create a D-Cube. 2. Click the appropriate cell, then from the D-Cube menu, click Annotations, Add/Edit. 3. Type in the annotation. A red dot in the top right corner of the cell indicates that a comment or annotation is attached.

Edit or View Cell Annotations

You can view annotations for a cell or range of cells to better monitor and track data in the D-Cube. You can also edit existing annotations to ensure that they reflect the correct information for a cell or range of cells within a D-Cube.

Steps
1. To view or edit a single cell annotation, right-click the required D-Cube cell and select Edit Annotation or Show Annotation. The name of the person who last edited the annotation is displayed together with the date and time it was altered. By clicking the D-Cube menu, pointing to Annotations, and then selecting Show, you will see the annotation in a single cell. 2. To view all cell annotations, from the D-Cube menu, click Annotations, Browse All.

User Guide 167

Chapter 8: D-Cubes

Remove Cell Annotations

You can choose to remove annotations that are no longer relevant from a single cell or a range of cells.

Steps
1. To remove annotations for single cell, right-click a cell and select Delete Annotation. 2. To remove annotations for a range of cells, highlight a range of cells, then from the D-Cube menu, click Annotations, Delete.

Specify Annotate Print Options

You set the orientation, printer, column width, and font in the Print D-Cube dialog box. In addition, you can select to print cell annotations.

Steps
1. Open a D-Cube and make a selection. 2. From the File menu, click Print or Print Preview. In the Annotations area, select or clear Print at the bottom of the page.

Edit Data
You can edit the data in a D-Cube by Typing directly in a cell Applying D-Cube commands (p. 173) Running D-Links

If a cube is open when the data changes are made, they will not be saved until you save the D-Cube. Changes made to a closed D-Cube are saved automatically. You can alter the appearance of data within a D-Cube by applying formats To individual D-List items (p. 117). Globally to the whole D-Cube (p. 191).

Edit Data on the Current Page of a D-Cube

You can edit the data on the current page of a D-Cube only when the D-Cube is open to that page.

Steps to type a new number

1. Click the cell with the number you want to edit. 2. Type the new data.

168 Analyst

Chapter 8: D-Cubes 3. Press Enter.

Steps to edit a number

1. Double-click the cell with the number you want to edit. 2. Type the changes. 3. Press Enter to calculate, ESC to cancel.

Steps to edit a green number (typed in but not entered)

1. Click the cell with the number you want to edit. 2. Press F2. 3. To return a green number to the original entered number, press ESC.

Edit the Data in Individual Cells Using Operators

The following abbreviations can be entered directly into cells. They operate on the underlying number held in a cell. These can be used in conjunction with the copy commands. Reset 10k 10m add100 or +100 sub50 or -50 mul1.1 or *1.1 div1.1 or /1.1 1000> Zero per10 or %10 inc10 dec10 Resets the value to the saved version (can be shortened to res). Enters the value 10,000. The suffix k (or K) denotes thousands. Enters the value 1,000,000. The suffix m (or M) denotes millions. Adds 100 to the value (can be shortened to a100). Subtracts 50 from the value (can be shortened to s50). Multiplies by 1.1 (can be shortened to m1.1). Divides by 1.1. Sets the value to 1000 and copies it across to the right. Sets the value to zero. Takes 10 percent of the value. Increases the value by 10 percent. Decreases the value by 10 percent.

User Guide 169

Chapter 8: D-Cubes

pow2 Hold Rel Lock grow10linear

Raises the value to the power of two. Holds the value to protect it from breakback. Releases or removes the hold. Locks or write-protects the value (can be shortened to l). Grows the value by 10 percent per period linearly (works with time periods only). Grows the value by 10 percent per period compounded (works with time periods only).

grow10compound

Examples - Copy Commands

inc10> 0>| reset| Increases the entire row to the right by 10 percent. Sets everything to the right and below to zero. Resets an entire column below the current cell back to the saved numbers. Grows the value by 10 percent for each period linearly (that is, increases the value by 10 percent of the original value each period) .

gro10li

Tip: Typing the word reset over a cell resets the number back to the saved version. Also, typing reset>, reset<, reset>|, reset ^, reset| resets cells to the right, left, above, and below.

Select a Range of Cells in a D-Cube

Selecting a range is a way to highlight cells before applying commands or copying and pasting data to and from the clipboard. The selected range displays with a black background. You can select a range of cells in a D-Cube only when the D-Cube is open.

Steps to select a range of cells in a D-Cube using the mouse

1. In the D-Cube, click the cell at which you want to start the range.

170 Analyst

Chapter 8: D-Cubes 2. Drag to select the desired range.

Step to select columns or rows

In the D-Cube, click the desired column or row headings, respectively.

Step to select the entire page

Click the blank gray cell just above the first row label (the top-left corner of the window).

Steps to select using the keyboard

1. Shift+ left, right, up, down arrow keys selects a range of cells. 2. HOME, then Shift+End selects an entire row. 3. Ctrl+Home, then Shift+Ctrl+End selects an entire page.

Reset Data
You can reset an entire D-Cube if you have not saved the changes. If you reset data by typing reset in a cell, you can also combine this command with copy commands to reset an entire row or column.

Steps to reset a column or row back to the last saved version

1. Open a D-Cube. 2. Right-click the row or column label you want to reset back to the saved version. 3. Select Apply Commands. 4. In the Apply to range dialog box, select reset from the list. See "Edit Undo and Redo" (p. 165). 5. Click OK. The cells revert to the blue and black colors, indicating data that has not changed since the last save.

Step for individual cells

Type the word reset or res directly into the cell and press.

When you reset individual cells in this manner, you can use reset in conjunction with the operators used to copy data.

Steps for a range of cells on the current page

1. Select the range of cells you want to reset. 2. Right-click the highlighted range. 3. Select Reset.

User Guide 171

Chapter 8: D-Cubes The selected range of cells revert to the saved version of the data.

Steps for a range of cells globally

1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Commands. 3. In the Apply to subselection of dialog box, click reset. For information about commands, see "Edit Undo and Redo" (p. 165). 4. Click Select. 5. In the Choose subselection dialog box, click the items from the Items available list, and then click Move>> to move the items to the Items included list. 6. Click OK. You are returned to the Apply to subselection of dialog box. 7. In the Apply to subselection of dialog box, click OK. The selected range of cells revert to the saved version of the data.

Recover from Errors

Most minor mistakes such as incorrect menu selections can be overcome by pressing the Esc key or clicking Cancel. Errors in data entry range in a D-Cube from entering a single wrong number to major structural errors in the D-Cube. Analyst provides comprehensive facilities to help you retrace your steps to recover from errors, even if it has been a while since you last saved the data. In increasing levels of severity, a summary of the options for error recovery are listed below.

Command
ESC

Recovery Action
Clears a green number (numbers typed in but not yet entered). Retraces one step at a time. Goes forward one step at a time. Reverts the cell data to the last saved version. Resets a selected cell to the last saved version.

Undo Redo Reset Right-click a cell, and then click Reset Reset from Apply to subselection dialog box

Resets a D-Cube range to the last saved version.

172 Analyst

Chapter 8: D-Cubes

Command
Reset Structure

Recovery Action
Resets a D-List contained in the D-Cube without changing the data. Resets data to the last saved version; it does not reset the D-Lists. Closes the file without saving.

Reset from the File menu

Close

D-Cube Commands
Ranges of data can be operated on using commands from the Commands menu.

Commands Menu
The available commands are zero, set, add, subtract, multiply, divide, percent, increase, decrease, reset, hold, release, lock, unlock, protect, unprotect, power, random and round.

Menu Command

Syntax example

Meaning

Example (Effect on a cell containing 1000)

Zero Set Add

zero set99 add10

Set range to zero Set range to a value

0 99

Add amount to underlying 1010 values Subtract amount from underlying values 990

Subtract

subtract10

Multiply

multiply1.2

Multiply underlying values 1200 by an amount Divide underlying values by 500 an amount Take a percentage of underlying values 100

Divide

divide2

Percent

percent10

Increase

increase10

Increase underlying values 1100 by a percentage

User Guide 173

Chapter 8: D-Cubes

Menu Command

Syntax example

Meaning

Example (Effect on a cell containing 1000)

Decrease

decrease10

Decrease underlying values 900 by a percentage Reset range to last saved version Last saved version

Reset

reset

Hold

hold

Hold the range of cells Blue background against breakback (p. 151) Cells can still be changed by entering or copying data or by D-Links.

Release

release

Remove the holds on a range

Blue background removed

Lock

lock

Write protect the range. Grey background Cells can still be changed by breakback but not by entering data or by D-Links Removes the locks on a range Grey background removed

Unlock

unlock

Protect

protect

Protects the range against Yellow background data entry by manual typing. The cells can still be changed by breakback or by D-Links. Removes the protects on a Yellow background range removed Raises the underlying values 1000000 to the power specified Changes the underlying values to random integers between zero and the number specified Random integer between zero and 100

Unprotect

unprotect

Power

Power2

Random

random100

174 Analyst

Chapter 8: D-Cubes

Menu Command

Syntax example

Meaning

Example (Effect on a cell containing 1000)

Round

Round10

Rounds the underlying values to the nearest number specified If you round a total, a breakback will be triggered, altering the details so that they add up exactly to the rounded number.

1000

Apply Commands
You can apply commands to a range of cells on the same page or to a range of cells across multiple pages of a D-Cube.

Steps for a range of cells on the same page

1. Open the D-Cube 2. Highlight the range of cells to which the command is to be applied 3. Do one of the following: Right click anywhere within the highlighted area. Select Apply Commands. Choose your command, adding any numeric details needed. From the D-Cube menu, click Commands. Choose your command, adding any numeric details needed. Click Marked selection. 4. Click OK. 5. Save the D-Cube.

Steps for a range of cells over multiple D-Cube pages

1. Open the D-Cube 2. From the D-Cube menu, click Commands. 3. Choose your command, adding any numeric details needed. 4. Click Select All to apply the command to the whole D-Cube or click Select to choose the data to which the command is to be applied. 5. If necessary, make your selection from the D-Cube selection box. 6. Click OK. User Guide 175

Chapter 8: D-Cubes 7. Save the D-Cube

Edit a Range of Data on the Current Page

You can change data in a range to facilitate data entry.

Steps
1. Open a D-Cube. 2. Select the range of data you want to change. 3. Right-click the selected range. 4. Select Apply Commands. 5. In the Apply to Range dialog box, select a command from the list. This command operates on the selected range. Most of the commands require you to type a number after them. 6. To calculate, click OK. In this example, increase15 increases the values in the highlighted range by 15 percent. Increase and decrease apply a percentage change to the underlying values, not an absolute change. Most of the commands are intuitive: add100 adds 100 to the number in every cell in the range; set1000 sets the number 1000 in every cell in the highlighted range. The commands operate on the selected range only. Changed numbers display in red.

Delete the Data from an Entire D-Cube

Deleting data from an entire D-Cube is similar to setting a global range to zero. It erases all data in a D-Cube, having first made sure that there are no hidden or locked cells. Before deleting data from a D-Cube, check for the following: hidden rows, columns, or pages locked cells protected cells

Check for Hidden Rows, Columns, or Pages

Before deleting data, ensure that there are no hidden row, columns or pages that are excluded from the deletion.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Selections, Reselect. 3. To select everything in the current D-List, click Clear. 176 Analyst

Chapter 8: D-Cubes 4. Repeat steps 1 through 3 for the remaining D-Lists in the D-Cube. 5. Click OK.

Check for Locked Cells

Locked data is used to prevent data entry and data loading, but does not prevent breakback. Before proceeding with deleting data from a D-Cube, you must unlock any data that is locked. Locked data cannot be deleted.

Steps
1. From the D-Cube menu, click Commands. 2. In the Apply to subselection of dialog box, select unlock, and then click Select All. 3. Click OK.

Check for Protected Cells

Cells are protected to prevent data entry. The protection does not prevent loading or breakback. Before deleting data, check to see that all protected cells are reverted to unprotected. Protected cells will not be deleted.

Steps
1. From the D-Cube menu, click Commands. 2. In the Apply to subselection of dialog box, select unprotect, and then click Select All. 3. Click OK.

Delete Data From an Entire D-Cube

You can delete data from a D-Cube to load a new set of data for the analysis you require.

Steps
1. From the D-Cube menu, click Commands. 2. In the Apply to subselection of dialog box, select zero, and then click Select All. 3. Click OK. 4. Save the D-Cube.

Set a Column or Row to Zero

You can modify sections of a D-Cube by using D-Cube commands to zero a column or row.

Steps to set cells to zero locally

1. Open a D-Cube. User Guide 177

Chapter 8: D-Cubes 2. Right-click the row or column label you want to set to zero. 3. Select Apply Commands. For information on commands, see "Change Ranges of Data Using Menu Commands" (p. 178). 4. In the Apply to Range dialog box, select zero from the list. 5. Click OK. The entire selection is set to zero.

Steps to set cells to zero globally

1. Open a D-Cube. 2. From the D-Cube menu, click Commands. 3. In the Apply to subselection of dialog box, select the list, and then select zero. For information about commands, see "Change Ranges of Data Using Menu Commands" (p. 178). 4. To have the command operate on a selected range of the D-Cube only, click Marked selection. 5. To have the command operate on the entire D-Cube, click SelectAll. 6. Click Select, and then select the items you want the commands to operate on. 7. Click OK.

Change Ranges of Data Using Menu Commands

Use commands to speed data entry.

Steps to Access Menu Commands

1. Select a range of cells in a D-Cube. 2. Right-click the range of cells. 3. Select a command from the following list: Copy Paste Copies the highlighted range to the clipboard. Pastes the contents of the clipboard into the highlighted range.

Paste Holds, Locks, Protects, You can copy and paste Holds, Locks, and Protects patterns from or All one D-Cube to another D-Cube, or all three patterns at once. Protect You can write protect a cell against manual entry or copying from the clipboard.

178 Analyst

Chapter 8: D-Cubes

Unprotect Lock Unlock Hold Release Reset Apply Commands

Remove the write protect from a cell. Locks or write-protects a range against data entry. Removes the locks from a range of data. Holds a range of data against change through breakback. Removes the holds from a range of data. Resets the range back to the saved version. Operates on the highlighted range. The commands available are zero, set, add, subtract, multiply, divide, percent, increase, decrease, reset, hold, release, protect, unprotect, lock, unlock, power, random, and round.

Add Annotation

You can provide further explanation of data.

Step to Access the Subselection List of Commands

From the D-Cube menu, click Commands.

Menu Syntax Command Example

Zero Set Add Subtract zero set99 add10 subtract10

Meaning

Example (Effect on 1000)

Set range to zero Set range to a value Add amount to underlying values Subtract an amount from the underlying values

0 99 1010 990

Multiply Divide Percent Increase Decrease

multiply1.2 Multiply underlying values by an amount divide2 percent10 increase10 decrease10 Divide underlying values by an amount Take a percentage of underlying values Increase underlying values by a percentage Decrease underlying values by a percentage

1200 500 100 1100 900

User Guide 179

Chapter 8: D-Cubes

Menu Syntax Command Example

Reset Hold Release Lock Unlock Power reset hold release lock unlock power2

Meaning

Example (Effect on 1000)

Reset range to last saved version Hold range against breakback Remove the holds on a range of cells Write-protect the range Remove the locks on a range of cells Raise the underlying value to a specified power

Back to saved Blue background

Gray background

1000000

Locks, Protects, and Holds

Applying a hold protects a cell against breakback. Applying a lock protects a cell against data entry. Applying a protect protects a cell against manual entry or copying from the clipboard. The commands may be used in combination to ensure that a cell cannot be changed at all it must be locked and held. You can also right-click a D-Cube to copy and paste Holds, Locks, and Protects patterns from one D-Cube to another D-Cube.

Why Data Can Change Despite Being Locked or Protected

Data can change in cells despite the fact that the lock or protect has been applied. The reason for this is the two-way arithmetic function named breakback. Although locked or protected cells are write-protected against direct data entry, they are not calculation-protected against breakback. This means that if a formula result is changed, its constituent parts can also change even if the constituent items are locked. For example, suppose a D-List item, North, has been locked or protected and data is entered in the Total Company cell containing the formula, Total Company = North + South + East + West. The breakback function is activated so that the North and other divisions change to meet the target set in the Total Company cell. The North division is changed as a result of the calculation being reversed, despite being write-protected against direct data entry. In the same way, locked or protected total cells can change if one of the constituent items that make up the total has changed. To write-protect and to protect against breakback, cells must be both locked and held (dark grey background) or protected and held (green background) if amendment by D-Link is permitted. For more information about the hold command see "Holds and Breakback" (p. 151).

180 Analyst

Chapter 8: D-Cubes

Hold Data
Hold is a type of control used to prevent breakback in a cell or a range of cells, but does not prevent data entry. Any user with Write access can remove the hold control from a D-Cube.

Hold or Release Individual Cells

The Hold and Release commands can be used in conjunction with the operators used to copy data. You can place a hold on individual cells of a D-Cube without preventing breakback in other areas of the D-Cube.

Steps
1. Open a D-Cube. 2. Choose whether to hold or release a cell: To hold a cell, type the word hold or H directly into the cell and press Enter. The letter H suffices instead of hold. To release a cell from Hold, type the word rel directly into the held cell and press Enter.

Hold or Release a Range of Cells on the Current Page

You can apply a hold on a range of cells in a D-Cube without preventing breakback in other areas of the D-Cube. For example, you may be required to re-forecast for the year when the actual data for January and February becomes available. You can release the Hold for January and February and continue to retain the hold on the remaining months that contain forecasted data.

Steps
1. Select the range of cells you want to hold or release. 2. Right-click the selected range. 3. To apply a hold, select Hold. The held cells display with a light turquoise background. 4. To release the hold, click Release. The blue background disappears to indicate that the hold has been removed.

Hold a Global Range of Cells Steps

1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Commands. User Guide 181

Chapter 8: D-Cubes 3. From the list of commands, select hold. 4. Click Select. 5. In the Choose subselection dialog box, do the following: In the Items available list, select the desired items, and then click Move>> to move the selected items to the Items included list. Repeat for all D-Lists. Click OK.

6. In the Apply to subselection dialog box, click OK. The held cells display with a light turquoise background.

Release the Holds from an Entire D-Cube Steps

1. Open a D-Cube in Full mode. 2. From the D-Cube menu, click Release All Holds. The blue background disappears to indicate that the holds have been removed.

Lock or Protect the Formula Cells Only

It is possible to apply a lock or protect to only the formula cells by selecting formulas in the selection screen. This is a useful way to prevent accidental entry of data into formula cells, particularly when a large amount of manual entry is required.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Commands. 3. From the list of commands, select lock or protect. 4. Click Select. 5. In the Choose subselection dialog box, do the following: In the Show box, select Formula. In the Items available list, select the desired items, and then click Move>> to move the selected items to the Items included list. Note: As a rule, do not repeat the selection of formulas for other D-Lists or you will end up locking just a few grand totals, not the desired result at all. Instead, leave the other D-List selections blank to mean 'select all'. Click OK.

182 Analyst

Chapter 8: D-Cubes In the Apply to subselection dialog box, click OK.

Protect Data
You may write-protect a cell or range of cells to prevent data being from entered manually by applying the Protect command. Protect differs from Lock in that data can still be transferred into a protected cell via a D-Link but you may not type data into a protected cell. By contrast, locked cells prevent data entry entirely whether by typing or via a D-Link. Protected cells are still vulnerable to break back if entering data into a subtotal that has a protected cell as one of its components (The Hold command is used if you want to prevent a cell from being altered by a break back).

Three methods to protect cells:

Type the word protect over a cell (or pr for short). Highlight a cell (or range of cells), then right-click the cells, and select Protect. Click D-Cube, Commands, protect, Select. Highlight the items to protect, and then click Move. Repeat for each D-List, and then click OK twice to return to the D-Cube. The color conventions are shown below.

Command
Protect Lock Hold Protect and Hold Lock and Hold

Background Color
Yellow Light Gray Light Turquoise Dark Green/Blue Dark Gray

Lock Data
Lock is used to prevent data entry and data loading, but does not prevent breakback.

Use the Lock Command to Write-Protect

The Lock command write-protects a range of cells against data entry. This means that data can neither be typed in manually, nor can it be pasted from the clipboard or copied using a D-Link. A locked range of cells is given a gray background. A range of cells that is held and locked is given a yellow background. Three methods to apply the lock or write-protect command:

User Guide 183

Chapter 8: D-Cubes You can type the word lock directly into an individual cell. This can be used in conjunction with the operators used to copy data. You can select a range, right-click it, and then select Lock from the shortcut menu. You can apply the lock to a selection of items in each D-List by clicking Commands from the D-Cube menu, and then clicking lock. This commands method is the most common method because it applies a lock to a selection across the entire D-Cube rather than to individual cells or rows and columns. Note: Like any command, locks can be applied only to a subset of the current selection. Ensure you have reselected all the D-List items you need before applying the locks or unlocks. In particular, this applies to unlocking cells using the Select All command, which selects all items from the current selection, not necessarily the entire D-Cube.

Steps to Lock or Unlock an Entire D-Cube

1. Open a D-Cube. 2. From the D-Cube menu, click Commands. 3. Choose whether to lock or unlock a D-Cube: To lock a D-Cube, from the list of commands, select lock. To unlock a D-Cube, from the list of commands, select unlock.

4. Click Select. 5. In the Choose subselection dialog box, in the Items available list, select the desired items, and then click Move>> to move the selected items to the Items included list. 6. Repeat for all D-Lists. 7. Click OK. You are returned to the Apply to subselection dialog box. 8. In the Apply to subselection dialog box, click OK. Locked cells display with a gray background. If the D-Cube is unlocked, the gray background disappears to indicate that the lock has been removed.

Steps to Lock or Unlock a Range of Cells on the Current Page

1. Open a D-Cube. 2. Choose whether to lock or unlock a range of cells:, select the range of cells you want to lock. To lock a range of cells, right-click the selected range and select Lock. The locked cells display with a gray background to show that they are write-protected. To unlock a range of cells, highlight the range of cells, right-click the range, and then select Unlock .

184 Analyst

Chapter 8: D-Cubes The gray background disappears to indicate that the lock has been removed.

Lock Individual Cells

The Lock command can be used in conjunction with the operators available for copying.

Steps
1. Open a D-Cube. 2. Type the word lock directly into the cell and press Enter (the letter L suffices instead of lock).

Special Copy and Paste

You can copy and paste Holds, Locks, and Protects patterns from one D-Cube to another D-Cube, or all three patterns at once. You must select the exact same range of cells, or a cell in the target D-Cube so the pasted area has the same shape as the selected area.

Steps
1. Open a D-Cube. 2. Select the locked, held, or protected cell or range of cells you want to copy. 3. Right-click the selected cell or range of cells and select Copy. 4. Select the cell or range of cells where you want to copy the hold, lock or protect patterns. 5. Right-click the selected cell or range of cells and click Paste Holds, Paste Locks, Paste Protects, or Paste All.

Random Number D-Cube Command

A D-Cube command named Random generates a random number. For example, random1000 would fill all items in the selection with a random integer between 1 and 1000. The empty selection would behave in exactly the same manner as the set command.

Round Command
The Round command lets you round a selection of D-Cube cells to multiples of any number. If you type round1 into a cell, it rounds to integers. Typing round100 into a cell will round to the nearest 100. And typing round0.1 rounds to one decimal place, and so on. Any rounding factor is allowed, and will always round to the nearest multiple of the number that you entered. If you type round12, it will round to the nearest dozen. Note: Rounding should not be applied to D-List formatted or date cells as it will round the underlying ID or date value respectively.

User Guide 185

Chapter 8: D-Cubes Rounding is also available using right-click > Apply Commands, or by selecting Commands from the D-Cube menu. Rounding can be put in a macro using the @DCubeCommand macro. You can also round any selection of cells, including totals. If you round a total, a breakback will be triggered, altering the details so that they add up exactly to the rounded number. The Round command is available in Analyst, Manager and Analyst for Excel.

Export Data
You may export data from a D-Cube in a variety of formats. The data must be in a format that is readable by the program to which you are exporting.

D-Cube Export
You may export data from a D-Cube to a text file (ASCII file) or to the clipboard.

Steps to Export From a D-Cube

1. Open a D-Cube. 2. From the D-Cube menu, select Export. 3. From the Export dialog box, select the options necessary and click Export. The Export tab contains the following options: Format Separator between columns for export can be Comma, Tab, Semi-colon or Aligned Columns. Column Headings can be set to Normal, At Top, Above Each Page or None. Normal is the default behavior. In multi-column view, it puts column headings above each page, but does not show the D-List names for the row and page dimensions. In single column view, Normal means that no column headers are shown. At Top puts the D-List names and column headers at the top only. Above Each Page puts the dimension names and the column headers above each page of the export. In single-column exports, the concept of pages is meaningless, so it only puts the dimension names at the top. None does not put any column headings in at all. Mode can be set to Overwrite or Append. Overwrite will overwrite an existing file of the same name, though it will prompt you before you replace the old file. If you export to a file that already exists, Append adds the exported data onto the bottom of the existing file. Groups can be set to Single or Multiple Column. Single Column exports the data values in a single column. Multiple Column means the data values are exported as a series of columns. For multiple column exports, the items in the last dimension (marked Data) are used as the column headers. Dimension Order

186 Analyst

Chapter 8: D-Cubes If you click the Dimension Order button, the export column order is set according to the underlying order of D-Lists in a D-Cube. It is independent of the current orientation of rows, columns and pages in the view you happen to have open. You may control the dimension order manually using the arrow buttons at the bottom of the export screen. Tip: When exporting from Analyst to Cognos Planning - Contributor it is much easier if you export in Dimension Order. It means you can export directly without having to go into SQL Enterprise Manager at all. Because Dimension Order is the default, you can run the Actuals.dts directly without having to change the dimension mapping in Data Transformation Services. Plain Number Format Removes any numeric formatting for the purposes of export. It exports to as many decimal places as are needed, up to the limit stored on the computer. Negative numbers will be prefixed by a minus sign and there will be no thousand separator or percent signs currency symbols or other numeric formats that have been applied on the D-List or D-Cube. Plain Number Format uses the full-stop as the decimal separator unless Apply Regional Settings overrides this. Text, D-List or date formatting will remain as displayed in the D-Cube view. Apply Regional Settings Examines the regional options (set in Control Panel) and uses this format for the thousand and decimal separator. For example, in Germany the number one thousand two hundred and thirty four point five six gets exported as 1.234,56, whereas in the UK and the USA, the same number has 1,234.56 as the export format. Pipes As Spaces The pipe symbol is used to mark a line break for wrapping column headers in Analyst. If you check Pipes as Spaces, the pipe symbol ( | ) gets replaced by a space on export. This is useful for exporting from Analyst to Contributor. Text Qualifier You can specify the text qualifiers for exporting text strings. These can be set to none, double quote or single quote by selecting from the Text Qualifier drop-down box. The text qualifier will be put around D-List items, text, and D-List formatted data cells. The default setting is none. Plain number format relates to exporting numbers. It will not control whether or not text qualifiers appear. The format for plain number format uses the regional setting in Control panel for the decimal separator, to set the number of decimal places to the minimum number to ensure complete accuracy, to use no thousand separator, and to show negative numbers with a leading minus sign and have no prefixes or suffixes. In the DCubeExport macro, the new parameter is added: TextQualifier = single, double, or none. This is not case-sensitive.

User Guide 187

Chapter 8: D-Cubes Note: If you have old macros that relied on the plain number format putting double quotes around the text strings, you may need to change these by inserting the option TextQualifier=double in the macro, but usually this is not necessary. Special Cases for text qualifiers If the name contains the text qualifier, it will double up the offending character to avoid ambiguity. For example: If you are exporting a text field containing 1/2" Drill bits to a file that uses double quotes as the text qualifier, it gets exported as "1/2"" Drill bits". Again, if a single quote is used in the name and as a qualifier, it gets doubled up for the export. So 12' ladder exported to a file with a single quote as the text qualifier will repeat the single quote to appear as '12" ladder'. Important: The only way to export numbers with comma delimiters is to use plain number format, or select a file separator other than a comma. Leading blanks Leading blank spaces are not stripped out when you export text or D-List-formatted cells. The Header/Footer tab contains the following options: You may insert your own header/footer to appear at the very top/bottom of the export file. The Zeros tab contains the following options: Suppress Zero Pages You can suppress zero pages for the export, independently of the zero-suppression currently in force in the view you have open on the screen (set under D-Cube>Options). Zero suppression is dimension specific. To suppress zero rows, highlight the dimension labelled R. To suppress zero columns, highlight the dimension labelled C. To suppress zero pages on all dimensions, select Suppress Zero Pages. To suppress zeroes everywhere, highlight all the dimensions and select Suppress Zero Pages. Note: Zero suppression of page dimensions requires Suppress Zero Pages to be selected. It is not sufficient to just put the zero suppression on the dimension. For multiple-column exports, suppression of zero columns is disallowed. This is essential to preserve the correct number and sequence of columns exported in a multiple-column export. Note: There is a special case where a row of zeroes gets exported even though Zero Suppression is ON. This occurs if Zero Suppression is OFF for the page labels, but ON for the row dimension. In this case, a blank page containing just the first row will still get exported. Zero-suppression on export is independent of the zero suppression set on the D-Cube. The Show Det/Tot tab contains the following option:

188 Analyst

Chapter 8: D-Cubes If you have chosen an Empty selection on a dimension (empty selections meaning All Items in this context), you can hide details or totals for the purposes of export. This option is dimension specific. This allows you to cut down the data volumes for the export file.

Export from Analyst to Contributor

Two methods exist for getting data from Analyst to Contributor. In Analyst, run an Analyst to Contributor D-Link (p. 276). This creates prepared import data blocks in the Contributor application data store. You can monitor this in the Contributor Administration Console, Import, Prepared data blocks screen. When the data blocks have been written, in the Contributor Administration Console, run the Go to Production process. Export data from Analyst to Contributor by exporting to flat text (ASCII) files, then import these files using the Contributor Import facility.

Export Data to Contributor Steps

1. In Analyst, open the D-Cube you wish to export. From the D-Cube menu, choose Export. 2. In the Export dialog box, change the settings to the following: Select Separator=Tab, Column Headings=None, Mode=Overwrite. Then select Single Column, Dimension Order, Plain Number Format, and Text Qualifier=none. See "Text Qualifiers" (p. 737) for more information. 3. In the Contributor Administration Console, use the Import facility to import the data, and then run the Go to Production process. See the Contributor Administration Guide or online help for more information.

Format Prior to Export

The data must be in a form readable by the program to which you are exporting. Generally this involves removing currency symbols, removing brackets for negative numbers and percent signs (%). To preserve accuracy, the numbers may need to be formatted to several decimal places. The most readable format is a format that shows the numbers to several decimal places (for accuracy) , does not use a comma separator for thousands, and uses a minus prefix (-) for negative numbers (for example, -1234.56). Often it is useful to save such a numeric format ready for loading when exporting data. Frequently, formats have been applied to individual D-List items rather than the D-Cube. So even after the D-Cube format has been set to a standard format, there are still rows and columns that have an inappropriate local format. The format on the D-List items must be temporarily changed to a standard format for exporting, and then reset to the old format after the export has taken place.

User Guide 189

Chapter 8: D-Cubes

Export to a Spreadsheet
The procedure for exporting data to a spreadsheet via the clipboard is almost identical to exporting via an ASCII file. Then only difference is that the data recorded with the clipboard is temporary, while data recorded in an ASCII file is permanent. Before exporting data, it must first be formatted. See "Format Prior to Export" (p. 189).

Steps
1. Open a spreadsheet. 2. Export the data from your D-Cube (p. 186). If you exported to an ASCII file, click the File menu, and then click Open. The exact syntax for importing from an ASCII file will vary depending on the version and spreadsheet. Name the file as preferred. Remember to change the search to all files (*.*) or it may search for files of the type .xls, .wk4, and so on. If you exported to the Clipboard, click the Edit menu, and then click Paste.

The file will be imported into the spreadsheet. Formulas and formatting are neglected. Blank lines may need to be inserted to separate different sections.

AutoSum
If you highlight a range of cells in a D-Cube view, the sum of the numbers highlighted is automatically displayed in the status bar at the bottom of the screen. This sum stays there until a different range of numbers is highlighted. You can choose from a list of predefined functions that return a single summary value for a group of related values.

Steps
1. Open a D-Cube and from the D-Cube menu, select Options, and then click the AutoSum tab. 2. Choose the type of summary value you want to show: To show the calculated value that represents the sum of the selected data items, click Sum. To show the average value of the selected data items, click Average. To show the number of selected data items, click Count. To show the minimum value of the selected data items, click Minimum. To show the maximum value of the selected data items, click Maximum.

3. Click OK. The summary value of the highlighted cells is displayed in the status bar at the bottom of the screen.

190 Analyst

Chapter 8: D-Cubes

Find Text and Character Matches

You can search for text strings or character matches in most screens that display text. This includes free-text and D-List formatted text in D-Cubes, formulas (click a cell and press F7), and audit trails.

Steps
1. Open a D-Cube. 2. Move the cursor to the point where you want to start searching, then from the Edit menu, click Find. 3. Type in the exact text you want to find. 4. You can search down a column or across a row by clicking the check boxes in the Keep Fixed area. 5. Select the Match Case check box to match the case of the text you entered with the text displayed on screen. 6. To jump to the next occurrence of the text string, from the Edit menu, click Find Next.

Formats
A format sets the form in which data displays and can be in numeric, date/time, or D-List (text) format. Use numeric formats (p. 112) to set decimal places, insert thousand delimiters, set braces for negative numbers, and set prefixes and suffixes. Use date and time formats to display dates and times (such as 6-Jul-97) as data in a D-Cube. Use D-List formats (p. 117) to enter text, restricting the text to the codes and names displayed in a selected D-List. Free text formats (p. 118) are allowed. You can name and save formats for repeated use.

Local vs Global Formats

A local format (p. 109) involves formatting D-Lists only and applies to an individual row or column. Generally, you apply local formats in the Format Attribute screen. A global format involves formatting an entire D-Cube. Generally, you apply global formats by clicking Format on the D-Cube menu. Although the two screens are almost identical, a D-Cube format is a general format applied to all data in the entire D-Cube, not just a specific item from a D-List. However, a local format applied to an individual row or column has priority over the global D-Cube format.

Load or Remove a Global Format

Steps
1. From the D-Cube menu, click Format. 2. Choose whether to load or remove a global format: User Guide 191

Chapter 8: D-Cubes To load a global format, select a format from the Format Type box, and then click Load. Select an existing saved format, and click OK. To remove a global format, select None in the Format Type box.

3. Click OK to apply. Note: If formats still remain after removing the global D-Cube format, they are local formats applied to items in the D-List. These can be removed by opening the D-List and setting the format on each item to <None>.

Save a Global Format

Steps
1. Open an appropriate D-Cube. 2. From the D-Cube menu, click Format. 3. Click a format from the Format Type box. 4. Format the D-List as desired. 5. Click Save to save the format under the same name - or Click Save As to save the format under a different name. 6. Enter the name of the format. 7. Click OK. 8. Close the D-List.

Enter Prefixes and Suffixes

You can enter any specific prefix or suffix for both negative and positive numbers. The default option sets a negative prefix and suffix so that negative numbers are enclosed in brackets. If you specify no negative prefix - that is, delete the open bracket, negative numbers are automatically prefixed with a minus sign (-). It is recommended to limit the prefixes and suffixes to 10 characters. The prefix and suffix let you display numbers with currency and other symbols as well as displaying different formats for negative numbers. For example, to display everything in dollars with brackets for negative numbers and the k suffix to denote thousands, use the prefixes and suffixes as shown below. This displays the number -1234 as ($1,234k).

Steps
1. Open a D-List. 2. Click the Format cell of the item you want to set decimal places to. 192 Analyst

Chapter 8: D-Cubes 3. Select Numeric from the Attribute list. 4. In the Prefixes or Suffixes areas, make your changes.

Access Blank if Zero

Select the Blank if zero option if you want zero values in the item to display as blank cells in the D-Cube. The default option is to display zero values in the D-Cube as normal. Note: With the Blank if zero option set, any value rounding to zero in the D-Cube displays as a blank cell. For example, if no scaling factor is set and decimal places is set to 2, the number 0.001 displays as a blank cell (or displays as 0.00 if the Blank if zero option is not set).

Steps
1. Open a D-List. 2. Click the Format cell of the item you want to apply a numeric format. 3. Select Numeric in the Attribute list.

D-Cube Selections
Using selections from a D-Cube allows you to hide rows, columns, or pages. This enables you to work on a subset of the data contained in a D-Cube. Saved selections may be used to save a specific D-Cube orientation. When selecting D-Lists for a D-Cube, the order of selection does not affect which D-Lists end up as rows or columns. In practice, the default setting designates the longest D-List as row labels, and any timescale D-List, or if there is no timescale D-List, the second longest D-List as column labels. This can be changed by transposing rows, columns, and pages as needed. However within a saved selection you are allowed to choose the D-Lists used as rows and columns so that the cube opens with your specified orientation. When a selection of a D-Cube is open, D-Links will only update the current selection. Global commands to change the data applied across a D-Cube will only affect the D-List items in the current selection. Working with a selection provides processing advantages by limiting memory usage for very large D-Cubes. However, if you select totals, the underlying detail items also require memory. A D-Link that needs to copy data to or from a total will also require memory.

Expanded Selections
When you open a limited selection from a D-Cube, only the items you selected are displayed in the D-Cube dialog box. If you have included formula items in your selection, however, an expanded selection may be opened internally, so that the selected formula items can be recalculated and broken back properly. Selections can also be used to do the following: Hide rows, columns or pages.

User Guide 193

Chapter 8: D-Cubes Sort rows, columns, and pages. Apply commands to a selection of rows, columns, and pages. Select which items to paste into a formula. Select where to position new items. Select items to delete. Order a D-List. Select a range of rows, columns, and pages for print. Select a range of rows, columns, and pages to export to another program.

If a basic selection includes formula items, the expanded selection will also include all the items on which the selected formula items depend, either directly or indirectly. For example, consider a Months D-List that contains twelve detail items (Jan, Feb, Mar, and so on), four quarterly totals (Q1 = Jan + Feb + Mar, and so on), and one full year total (Full Year = Q1+Q2+Q3+Q4). If you open a D-Cube containing this D-List and select only Q1 from MONTHS, the expanded selection will include Q1 and Jan, Feb, and Mar. If you select only Full Year, the internal expanded selection will include all items in the MONTHS D-List. Remember that Analyst does not save calculated data in the D-Cube when it is closed; data in formula items is only recalculated when required. Selections can be saved for later use. For example, a retail chain might wish to group similar stores into a selection so that budgeting assumptions can be applied to the selection of stores without having to modify each page of data.

Creating a Selection
Various methods are available for creating a selection depending on whether the D-Cube is currently open.

Blank Selections
If the Items included list in the Selection dialog box is left completely blank, every item in the list will be selected. For saved selections, leaving the Items included list blank selects everything including future insertions of extra D-List items. There is a subtle distinction between blank selections and selecting every item: Blank selections from a D-List will select all items; so if items are added, the new items will be loaded with the saved selection. If, however, you save a selection that shows all the D-List items in the Items included list, new items will not be inserted when the saved selection is loaded.

194 Analyst

Chapter 8: D-Cubes

Reselecting after changing data

Beware of reselecting after you have changed data. If, as a result of the reselection, you hide detail items that contain altered data (colored red and pink), these changes will be lost and the cells will be reset to their saved values.

Steps if the D-Cube is Not Open

1. Click the Open D-Cube icon. 2. Click the radio button for Edit Selection and click OK. 3. Make your selection of D-List items (p. 195) to be included choosing from each D-List in the cube by clicking their tabs. 4. Click Slice to specify the D-Cube orientation. 5. Click Save to save the selection you have chosen. 6. Name your selection. 7. Click OK to the View Saved message. 8. Click OK to open your selection.

Steps if the D-Cube is Already Open

1. From the D-Cube menu choose Selections and Reselect. 2. Make your selection of D-List items (p. 195) to be included choosing from each D-List in the cube by clicking their tabs. 3. Click on Slice to specify the D-Cube orientation. 4. Click OK. 5. From the D-Cube menu choose Selections and Save current. 6. Give your selection a name. 7. Click OK.

Facilitate Selection Using the Selection Dialog Box

Within this box, items in any D-list are split into two lists: The Items included list shows items that have been selected. The Items available list shows items that are available, but have not been selected.

To facilitate selection especially from long D-lists, the following features are available:

User Guide 195

Chapter 8: D-Cubes

Show Box
The Show box allows you to reduce the number of items in the Items Available list. It does not select items in its own right, but merely determines the choice of Items Available. Select All to show the full D-List. Select Detail to show detail items only - for example, all D-List items apart from formulas. Select Formula to show only the formulas. Select Filter to show a selection based on a keyword, initial letter, or a text search criterion. It filters the text in the D-List items only, not the values contained in the cells. Wildcard characters are allowed in the filter. Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters.

The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria.

Order Box
The Order box sorts the Items available list to assist in selection. It does not sort the Items included list itself. The options are as follows: Normal - sorts by the normal D-List order. Alphabetic - sorts alpha-numerically. Rev Alphabetic - sorts reverse alpha-numeric. Totals - sorts by expanding the subtotals in the order they appear in the D-List.

Because the Order box only sorts the Items available list, any sorting using the Order box requires moving items from the Items available list to the Items included list by clicking Move >>. The Order by Totals feature is not available when reordering D-Lists permanently, but is available when reselecting from D-Cubes.

Steps
1. Select the appropriate items from the Items available list. Ctrl+Click to highlight non-adjacent items. Click All to select all items. Click Search to search for items (generally for long D-Lists). Click Expand to expand selected totals in either the Items Available list or the Items Included list.

196 Analyst

Chapter 8: D-Cubes Click Slice to specify the D-Lists top be used as rows and columns in the selection

2. Click Move >> to move the selected items to the Items Included list. A blank selection implies select all. 3. In the Items included list, click Sort to sort the items in the Items Included list. Use the Sort Arrows to sort the items. 4. Click Clear to clear the entire selection. 5. Click Reset to reset the selection back to its original format.

Saved Selections and D-Links

If working on a sub-selection from a D-Cube, data can not be entered or imported via D-Links into an unselected and unopened range of cells. Only an open range of cells will be updated when a D-Link is executed.

Save a Selection
Saved selections may be used to save a specific D-Cube orientation, including a selection of rows, columns and pages for later use. The selected items, sort order, and slice of the D-Cube are all saved in a named selection. When saving a selection, it is recommended that the selection name is similar to the D-Cube name.

Steps to Save the Current Selection of a D-Cube

1. From the D-Cube menu, click Selections, Save current. 2. Name the current selection.

Steps to Save a Selection in the Selection Screen

1. From the D-Cube menu, click Selections, Reselect. 2. Make your changes in the Selection dialog box (p. 195). 3. Click Save. 4. Specify the save. Click Save selection if you have just loaded and edited the selection. Click Save selection as to save the modified selection under a new name.

Note: The program only knows you are working on a saved selection when you have just loaded it, edited it, and have not left the selection screen. So if you have accessed the main screen in between loading and saving, the program will not remember the name of the original selection. Consequently it will ask you for a new name regardless of whether you choose the Save selection or Save selection as options.

User Guide 197

Chapter 8: D-Cubes 5. Name the selection. 6. Click OK when prompted. 7. To recall a saved selection, load (p. 198) the selection.

Load a Saved Selection

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Selections, Reselect. 3. Click Load in the Selection dialog box (p. 195). 4. Select one of the previously saved selection names. 5. Click OK. 6. The saved selection is loaded. 7. Click OK in the Selection dialog box. 8. To open a different selection, repeat the process by returning to the selection screen and clicking Load once more.

Load a Saved Selection on Opening a D-Cube

Steps
1. From the File menu, click Open, D-Cube. 2. Select the D-Cube to open. 3. Select Saved Selection when prompted. Note: The D-Cube must have been saved as a selection before loading. For more information about saving a selections, see "Save a Selection" (p. 197). 4. Choose the saved selection. 5. Click OK. 6. The D-Cube will open with just the items from the saved selection.

198 Analyst

Chapter 8: D-Cubes

Edit the Selection on Opening a D-Cube

Steps
1. From the File menu, click Open, D-Cube. 2. Select the D-Cube to open, select Edit Selection when prompted, and then click OK. 3. In the Selection dialog box (p. 195) Items available list, click the appropriate D-List tab. 4. Make your selection from the Show box. Select All to show the full D-List. Select Detail to show detail items only, such as all D-List items apart from formulas. Select Filter to show a selection based on a keyword, initial letter or a text search criterion. It filters the text in the D-List items only, not the values contained in the cells. 5. Make your selection from the Order box. Normal - sorts by the normal D-List order. Alphabetic - sorts alpha-numerically. Rev Alphabetic - sorts reverse alpha-numeric. Subtotal - sorts by expanding the subtotals in the order they appear in the D-List.

Because Order sorts only the Items Available list, any sorting using Order must be followed by Move >> to move the ordered items to the Items Included list. The Order by Subtotal feature is not available when reordering D-Lists permanently, but is available when reselecting from D-Cubes. 6. Select the appropriate items from the Items Available list. Ctrl+Click to highlight non-adjacent items. Click All to select all items. Note: Clicking All applies the selection, but does not specify whether the selected items are to be included or not. After clicking All, the selected items must be moved to the Items Included list or the Items Available list using Move. Click Search to search for items (generally for long D-Lists). Wildcard characters are allowed in the filter. Use a question mark (?) to represent any single character. Use the multiplication symbol (*) to represent any series of characters. Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters. The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria.

User Guide 199

Chapter 8: D-Cubes Click Expand (p. 157) to expand selected totals in either the Items available list or the Items included list. Click Slice to choose which D-List you would like to appear as rows and which you would like to have as columns. The Slice command is similar to the pivot command in certain spreadsheets, but much more extensive in its scope. The orientation of a D-Cube can be changed so that pages become columns, rows become pages or columns become rows. In fact, any orientation is possible. For four and five-dimensional D-Cubes, simply choose any two of the D-Lists to make up the rows and columns, leaving the other D-Lists to become pages. The slice can be saved with a named selection. 7. Click Move >> to move the selected items to the Items included list. A blank selection (p. 194) implies select all. 8. In the Items included list, click Sort to sort the items in the Items included list. Use the Sort Arrows to sort the items. The D-List order is the default order that rows, columns, and pages will appear in the absence of any numerical or other sort. Generally, the D-List order is the order that items were typed into the D-List when it was first created. Normal is for the order held in the D-List. Alphabetical for alpha-numeric. Rev Alphabetical is for reverse alpha-numeric. 9. Click Clear to clear the entire selection. This is made permanent only when you save an object. 10. Click Reset to reset the selection back to its original format. Clicking Reset reverts to the last saved version you were working with, not necessarily the saved selection. This can be applied to data in individual cells, to a highlighted range on the current page, to a global range across a D-Cube, or to an entire D-Cube. The reset command can be applied to the data, the D-Cube structure, or both. Resetting the structure of a D-Cube allows you to cancel changes that have been implemented (not saved) in the underlying D-Lists as well as any D-Cube sorts and formats. For more information about resetting the structure of a D-Cube, see "Reset the Structure of a D-Cube" (p. 206). Note: Reset does not reset a slice. 11. Ensure any items you want to show are in the Items included list. 12. Click OK.

Edit a Saved Selection

Steps
1. In the Selection dialog box (p. 195), look at the Items available list.

200 Analyst

Chapter 8: D-Cubes 2. Click the appropriate D-List tab. 3. Make your selection from the Show box. Select All to show the full D-List. Select Detail to show detail items only, such as all D-List items apart from formulas. Select Filter to show a selection based on a keyword, initial letter or a text search criterion. It filters the text in the D-List items only, not the values contained in the cells. 4. Make your selection from the Order box. Normal - sorts by the normal D-List order. Alphabetic - sorts alpha-numerically. Rev Alphabetic - sorts reverse alpha-numeric. Subtotal - sorts by expanding the subtotals in the order they appear in the D-List.

Because Order sorts only the Items Available list, any sorting using Order must be followed by Move >> to move the ordered items to the Items Included list. The Order by Subtotal feature is not available when reordering D-Lists permanently, but is available when reselecting from D-Cubes. 5. Select the appropriate items from the Items available list. Ctrl+Click to highlight non-adjacent items. 6. Click All to select all items. Note: Clicking All applies the selection, but does not specify whether the selected items are to be included or not. After clicking All, the selected items must be moved to the Items Included list or the Items Available list using Move. 7. Click Search to search for items (generally for long D-Lists). Wildcard characters are allowed in the filter. Use a question mark (?) to represent any single character. Use the multiplication symbol (*) to represent any series of characters. Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters. The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria. 8. Click Expand (p. 157) to expand selected totals in either the Items available list or the Items included list. 9. Click Slice to choose which D-List you would like to appear as rows and which you would like to have as columns. The Slice command is similar to the pivot command in certain spreadsheets, but much more extensive in its scope. The orientation of a D-Cube can be changed so that pages become columns, rows become pages or columns become rows. In fact, any orientation is possible. For

User Guide 201

Chapter 8: D-Cubes four and five-dimensional D-Cubes, simply choose any two of the D-Lists to make up the rows and columns, leaving the other D-Lists to become pages. The slice can be saved with a named selection. 10. Click Move >> to move the selected items to the Items included list. A blank selection (p. 143) implies select all. 11. Look at the Items Included list: 12. Click Sort to sort the items in the Items Included list. 13. Use the Sort Arrows to sort the items in the Items Included list. Click Clear to clear the entire selection. 14. Click Reset to reset the selection back to its original format. Clicking Reset reverts to the last saved version you were working with, not necessarily the saved selection. This can be applied to data in individual cells, to a highlighted range on the current page, to a global range across a D-Cube, or to an entire D-Cube. The reset command can be applied to the data, the D-Cube structure, or both. Resetting the structure of a D-Cube allows you to cancel changes that have been implemented (not saved) in the underlying D-Lists as well as any D-Cube sorts and formats. For more information about resetting the structure of a D-Cube, see "Reset the Structure of a D-Cube" (p. 206). Note: Reset does not reset a slice. 15. Ensure any items you want to show are in the Items included list. 16. Save the selection by clicking Save on the Selection screen. 17. Click OK to return to the edited D-Cube.

Manage D-Cubes
Memory Management
For very large D-Cubes, you may see a message that states Workspace full, or Memory running low. To increase the maximum capacity, switch off the stored copy. This has the effect of switching off the colors. You have increased memory usage when the program displays changed numbers in red, because it compares two versions side by side in memory. By removing this facility, you effectively double the capacity of the largest D-Cube. The ability to reset the whole D-Cube back to a stored version remains unaffected, although reset will not be available on individual cells or selections.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Options and then select the Stored Copy tab. 202 Analyst

Chapter 8: D-Cubes 3. Clear the Create Stored copy check box. The size of the D-Cube you open increases by a factor of up to two, but it no longer displays changed numbers in different colors.

Split Column Headings onto Two Lines

Column labels may be split onto two or more lines (same as a soft return) by editing a D-List item and typing the pipe symbol | (shift+\ on most keyboards) to indicate a new line.

Steps
1. Open the D-List. 2. Double-click the item name or press f2 while in the Item name column. 3. Type a pipe symbol ( | ) where you want to indicate a new line. 4. Repeat as necessary. The D-List item splits onto a new line when it appears as a column label. The pipe symbol is not usually visible except in references to the D-List item such as in formulas. 5. Save the D-List.

Show Details or Formulas Only

You may wish to show just formula items or just details in a D-Cube. There are two methods of doing this.

Steps Using the Selection Dialog Box

1. Open a D-Cube. 2. From the D-Cube menu, click Selections, Reselect. - or Click the Reselect D-Cube button. 3. Select Formulas (or Details) from the Show box. 4. Click All to highlight the items in the Items available list. 5. Click Move to move them to the Items included list. 6. Click OK.

Steps from the D-Cube

1. Open a D-Cube. 2. Right-click the row or column labels.

User Guide 203

Chapter 8: D-Cubes 3. Choose whether to show or hide Totals or detail items: To hide totals or details, click Hide Totals or Hide Details from the menu. To show totals or details, click Show Totals or Show Details

Sort Rows, Columns, and Pages

Sort Rows or Columns Based on Numeric Values
Lists may be sorted based on the value of the data contained in the D-Cube You must decide which D-List to sort, the sort order (ascending or descending), and the criterion on which to base the sort. Multiple sort criteria are not permitted although it is possible to sort rows and columns independently.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Sort. 3. Select the D-List from the Sort Items in D-List box. 4. Click Edit Selection to select specific D-List items. Make your changes in the Select Items to Sort dialog box. 5. Click Ascending or Descending to sort the data in ascending or descending order. Note: The Select items to sort dialog box is identical to the Selection dialog box. For more information about the selection dialog box, see "Facilitate Selection Using the Selection Dialog Box" (p. 195). 6. Select the D-List from the Based on Contents of D-Lists box. 7. Click the Item Name box and select an item on which you will base the sort. 8. Click OK. 9. Click OK in the Sort Options dialog box.

Sort Rows on One Criterion, Columns on Another

It is possible to sort rows on one criterion, columns on another. For example, rows could be sorted based on the values in the Total company column, while the columns could be sorted based on the values in Q1 (the first quarter). The sorts are applied independently.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Sort. 3. Select the D-List from the Sort Items in D-List box. 204 Analyst

Chapter 8: D-Cubes 4. Click Edit Selection to select specific D-List items. Make your changes in the Select items to sort dialog box. 5. Click Ascending or Descending to sort the data in ascending or descending order. Note: The Select Items to Sort dialog box is identical (except for the title) to the Selection dialog box. 6. Select the D-List from the Based on Contents of D-Lists box. 7. Click the Item Name box and select an item on which you will base the sort. 8. Click OK. 9. Repeat this procedure for a second D-List in the same D-Cube.

Remove a Numerical Sort Steps

1. Open a D-Cube. 2. From the D-Cube menu, click Sort. 3. Locate the D-List containing the numerical sort you would like to remove. 4. Click the Item Name box. 5. Select <None> from the Item Name box. 6. Repeat for other combinations of D-Lists for which you want the sort removed. 7. Click OK. 8. Click Edit Selection to select specific D-List items.

Manipulate D-Cube Structure

You can change the perspective of a D-Cube by moving D-Lists between rows, columns, and pages, or by selecting different items on pages. Exchanging the positions of D-Lists does not affect the order of the D-List or calculation in a D-Cube. It only changes how the D-Cube is displayed.

Slice a D-Cube
You can re-orient a D-Cube to change the business perspective of your data.

Steps
1. Open the appropriate D-Cube. 2. From the D-Cube menu, click Selections, Reselect - or -

User Guide 205

Chapter 8: D-Cubes Click the Reselect D-Cube button. 3. Click Slice, and then select the D-Lists to make up the rows and the columns. 4. Click OK.

Reset the Structure of a D-Cube

The structure of a D-Cube comprises formatting, lines, sorting, zero suppressions, and, of course, the D-Lists comprising the D-Cube. In short, the structure comprises everything that makes up a D-Cube, apart from the data itself. Resetting the structure resets any changes to D-Lists contained in the D-Cube that were implemented using the Implement command from the D-List menu. This resets any calculation changes, changes to item names, averages, local D-List formats, recent insertions of rows and columns, numeric sorts, column and row widths, zero suppressions, and D-Cube formats. The data in the D-Cube is not reset although formula results might change as a result of resetting the D-Lists. Resetting the structure does not include resetting to saved selections or reverting to the saved integer or decimal mode for breakback. It does not reset D-Lists if they have been saved. It also does not reset the changes of dimensions that have been added, deleted, substituted, or reordered.

Steps to Reset the Structure of a D-Cube

1. Open a D-Cube. 2. From the D-Cube menu, click Reset structure. The underlying D-Lists are reset to their last saved versions.

Steps to Reset the Structure and Data

1. Open a D-Cube. 2. Open each D-List in the D-Cube. 3. From the File menu, click Reset for each D-List. At the prompt, click Yes. 4. With the D-Cube active, click the File menu, and then click Reset for each D-List. 5. When prompted to reset the data in the D-Cube to the saved version, click Yes.

Transpose Rows and Columns

Transposing causes the rows and columns to be swapped. Only the rows and columns are swapped, the pages remain the same.

Steps
1. Open a D-Cube. 2. Click the Transpose button. 3. To revert back to the original configuration, click the Transpose button again.

206 Analyst

Chapter 8: D-Cubes

Show a Full Selection of All Rows, Columns, and Pages

To show all rows, columns, and pages you must select all D-List items from all the D-Lists.

Steps
1. From the File menu, click Open, D-Cube. 2. Select the D-Cube to open. 3. Select Full when prompted. 4. Click OK. All D-List items are selected including any new ones that have been added since you last opened the D-Cube.

Reselect a D-Cube Steps

1. Open a D-Cube. 2. Click the Reselect button 3. Click the appropriate D-List tab. 4. Select items from the Items available box, and then click Move >>. The items are placed in the Items included list and will be displayed in your D-Cube. 5. Click OK. 6. Click Yes when prompted.

Work with Dimensions

You can choose D-Lists that will make up a D-Cube. This process includes adding D-Lists in the order of category number to maintain the correct precedence of calculation.

Add Dimensions to a D-Cube

Rows, columns, and pages (dimensions) may be inserted by adding D-Lists to a D-Cube.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Dimensions, Add. 3. Click Yes when prompted. 4. In the Select D-List to add dialog box, click the appropriate library. 5. Click the appropriate D-List.

User Guide 207

Chapter 8: D-Cubes 6. Click OK. 7. In the Select the position for the new dimension dialog box, select the order in which you would like the D-List added (row, column, or end of list). Note: When selecting the order, keep in mind that this may affect the order of D-List priority. 8. Click OK. 9. In the Select the item to which the current data belongs dialog box, select the appropriate items from the Items available box, and then click Move >>. Note: The program will incorporate the existing data from the D-Cube into the selected item. However, when adding a D-List containing subtotals, the subtotal cannot be chosen because a break back is not possible. For example, suppose the value for Monthly Sales Staff on Hand is seventy-eight. If you were to add a Months D-List and specify Full Year (which is the sum of all the months), the program would not allocate 78 pro-rata across the months. 10. Click OK. If the Items Included list in the Selection dialog box is left completely blank, all items from the Items Included list will be selected. 11. Click OK again. 12. Save the D-Cube.

Delete Dimensions (Rows, Columns, or Pages) from a D-Cube Steps

1. Open a D-Cube. 2. From the D-Cube menu, click Dimensions, Delete. 3. Select a dimension to delete In the Select dimension to delete box. 4. Click OK. 5. In the Select the item to which the current data belongs dialog box: Select the appropriate items from the Items available box, and then click Move >>. Note: The program will incorporate the existing data from the selected items to be deleted with the dimension into the D-Cube. Click OK.

If the Items included list in the Selection dialog box is left completely blank, the program will select everything. 6. Click OK. 7. Save the D-Cube.

208 Analyst

Chapter 8: D-Cubes

Substitute D-Lists Within a D-Cube

When you substitute a dimension within a D-Cube, you need to decide how to match old D-List items to the new ones that take their place. This is simple where there is a one-to-one substitution between the outgoing item and the incoming item, but there are cases where many items must be substituted by a single item. It is important to note that only detail items will preserve their data on substitution. If you replace calculated items with detail items then any data previously held against the calculated items will be lost.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click Dimensions, Substitute. 3. Click Yes when prompted. 4. Select a D-List in the Select D-List to use as a substitute dialog box. 5. Click OK. 6. Select the dimension (a D-List from the D-Cube) to substitute. 7. Click OK. 8. Pair the items in the Old->New: Match Items dialog box. If a calculated item in the old list is being replaced by a detail item, then carry out the following procedure prior to substitution. In the old D-List, enter a new dummy detail item for every calculated item to be replaced. Use an internal D-Link to copy the D-Cube data from the calculated items to the new detail items you have inserted. On substitution match these new detail items with the detail items in the new list. Summation does not calculate weighted averages when substituting D-Lists. Assume you want to substitute a Months D-List with a Quarters D-List (as in this example): Suppose the item Unit Price is a weighted average, weighted by number of units sold. In each of the three months in a quarter the unit price is 10. When you add three months worth of Unit Price to go into one quarter, the values will be summed to display 30 ((10 + 10 + 10), which is incorrect. The correct average figure is 10. When substituting D-Lists that contain weighted averages, it is better to enter a subtotal and a corresponding detail item to which to link the data (as above) prior to substitution so that a one-to-one match is possible. 9. Click OK.

Substitute a D-List Used by Several D-Cubes

You may substitute a shared D-List across several D-Cubes in one operation. Typically this might be a new set of account codes or a new cost-center structure that must be substituted across an entire model.

User Guide 209

Chapter 8: D-Cubes Note: Data will be lost if you do not define a replacement match for each of the old D-List items. Although the substitution will make D-Links, macros and selections refer to the new D-List. The allocation table that defines how old and new D-List items correspond will not be used to update these objects. Consequently all D-Links, Selections and Macros must be checked and edited after a substitution of a D-List so that the items correspond.

Steps
1. From the File menu, click Libraries, D-Lists. 2. Click the Show objects that the selected object(s) is used by button to reveal the D-Cubes and other objects that use the selected D-List 3. Click the down arrow button to select all the D-Cubes, D-Links and other objects that use the old D-List. 4. Right-click and select Substitute D-List. 5. Select the new D-List to be used as a substitute. 6. Select the old D-List to be replaced. 7. Set up the correspondence between the old D-List and the new D-List, and then click OK. You will be prompted to confirm the substitution of the D-List in the objects selected. 8. Click Close to return to the main screen.

Effect on D-Links When Dimensions Are Altered

If you have added (p. 207), deleted (p. 208), or substituted (p. 209) a D-List, the D-Links must be edited. No attempt will be made by the program to update the source and target items in a D-Link even in cases where there is a one to one correspondence on substitution. Even in cases where you are matching descriptions in the D-Link, the substituted D-List will not be matched. If you attempt to run the D-Link you will receive the message stating "D-List xxxxx has been deleted from the D-Cube. The D-Link must be edited." If a D-List is substituted, the old D-Links will not function. For example, suppose you were to substitute a dimension in the place of an existing D-List. If you attempt to run the D-Link you will receive the message stating "D-List xxxxx has been deleted from the D-Cube. The D-Link must be edited". When you edit the D-Link a message will appear saying "The dimension xxxxx can no longer be found in the D-Cube. The D-Link will be updated accordingly". Click OK and edit the D-Link. Matching descriptions, allocation, or single item selection must be set up for the new D-List and the D-Link must be saved. When a D-List is added a similar situation occurs, although the old D-Link will still run. Most likely, however, the D-Link must still be edited. Matching descriptions, allocation, or single item selection would usually need to be set up for the new D-List. If the D-Link is not edited, a default selection for the new D-List will be left blank.

210 Analyst

Chapter 8: D-Cubes If a D-List is deleted, the old D-Links will not function. For example, suppose you were to delete an existing D-List. If you attempt to run the D-Link you will receive the message "D-List xxxxx has been deleted from the D-Cube. The D-Link must be edited." When you edit the D-Link a message will appear saying "The dimension xxxxx can no longer be found in the D-Cube. The D-Link will be updated accordingly". Click OK and edit the D-Link.

Effect on Formats when Dimensions are Altered

Formats attached to a D-List item will not be reassigned. Suppose you were to substitute a D-List with a new one. When one D-List item is substituted for another the format of the old D-List item will not be inherited, even in cases where there is a one-to-one correspondence on substitution.

Reorder the Dimensions of a D-Cube

You can set priorities, but they are not required. However, to ensure that formulas always give sensible results, follow these rules:

Priority Rule 1
Always set percentages, ratios, prices, and any per unit measure as weighted averages that are weighted by the denominator. For example, price per unit must be weighted by the number of units.

Priority Rule 2
When setting up the D-Cube, choose the D-Lists in an order that uses the calculation D-List first and the aggregation D-Lists last. For example, a typical D-Cube is set up to use four D-Lists in the order: P&L Divisions Time Actual/Budget/Variance

This ensures that the additions along the Time dimension override formulas of equal priority on the P&L dimension. Variances are calculated last. This is of particular importance when using IF THEN ELSE formulas on the P&L dimension. Generally, conditional formulas should have low priorities.

Priority Rule 3
As a last resort, change the individual priorities of formulas so that the results come out correctly. In practice, changing formula priorities is very rare, but setting weighted averages is a common occurrence.

Steps
1. Open a D-Cube.

User Guide 211

Chapter 8: D-Cubes 2. From the D-Cube menu, click Dimensions, Reorder. 3. To change or view the existing order, click Yes. Note: Although you are told that the operation cannot be undone using the undo facilities, you can always repeat the operation backward to reset the order to the original. 4. In the Reorder dimensions dialog box, select the new order of D-Lists using the arrows. 5. Click OK.

Navigate Around a D-Cube

Using the keyboard, press the following shortcut keys to move around the D-Cube.

Keys
Arrow Keys Tab Home Ctrl+Home End+Home Page Up Page Down Ctrl+Page Up Ctrl+Page Down

Action
Move one cell to the left, right, up, or down Move one cell to the right Move to the beginning of the current row Move to the top-left corner of the page Move to the bottom-right corner of the page Move up a screen, remaining on the current page Move down a screen, remaining on the current page Move to the previous page Move to the next page

Use the mouse to scroll quickly around the D-Cube by clicking the desired cell. To jump to a cell that is off the screen, drag the scroll bars. Alternatively, click the label box of a D-List and jump to a new row or column.

View a Different Slice

A D-Cube can be changed so that you can view a different slice of the D-Cube data. For example, in a D-Cube with the dimensions Centrally Allocated Items by Versions by Periods, one slice would have Centrally Allocated items as row labels, Periods as column headings, and Versions as pages. Another slice would have Versions as row labels, Periods as column headings, and Centrally Allocated Items as the pages. Yet another slice would show Centrally Allocated Items as rows, Versions as columns, and Periods as pages. There is no limit to how the data can be sliced. In four- and

212 Analyst

Chapter 8: D-Cubes five-dimensional D-Cubes you are simply selecting two dimensions to make up the rows and column labels, leaving the remaining dimensions to make up the pages. However it is important to note that within analyst it is not possible to have multiple or laminated dimensions making up the rows or columns. To do this, you must use Manager or the Analyst for Excel.

Steps
1. Click the page label box (the four-headed arrow appears). 2. Drag the page label box to the center of a column heading. In the new slice, the old page labels become the new column headings (and vice versa). To view a new slice and end up on a specified page drag the four-headed arrow from the page label box to the column label box. of the item. For example, if you have a months D-List forming the columns in your current view and Versions forming the pages, and you wish to make Versions the columns and view the October page, then drag the four headed arrow over the October columns label.

View a Different Page

Step Using the Keyboard
Choose one or more of the following keys: Ctrl+Page Up - Move to the previous page. Ctrl+Page down - Move to the next page. Ctrl+Tab - Move to a different dialog box.

Step (right-click the mouse)

Right-Click the Page Label box and select Next or Previous. Note: If you change the page, all numbers in green (typed but not entered) are lost. To prevent this, press enter to calculate before changing the page.

Steps (click the page label box)

1. Click the page label box. 2. Select the page you want to view from the list. 3. Double-click the selected page.

Save D-Cubes
Saving a current cube saves any D-Cube formatting, lines, column and row widths, breakback mode, and zero suppression settings. User Guide 213

Chapter 8: D-Cubes You can also save a copy of an open D-Cube under a different name. The old D-Cube is closed and reverts to its last saved version. Any outstanding changes are saved in the new D-Cube, not in the old one. Unlike the copy facilities in the library, D-Links are not copied when the file is saved under a different name. To save any changes to the formulas in the D-Lists, the D-Lists must be saved.

Step
Choose whether to save an existing cube or save the cube under a new name: To save the existing cube, from the File menu, click Save. Clicking Save does not save the current slice and selection. To do this, from the D-Cube menu, click Selections, Save current. You must give the selection a name. You can load the selection at a later date when you reopen the D-Cube. To confirm the save of the D-Cube, click Yes. The data color changes from pink or red to blue and black (details and formulas) to show that the data is saved. Any changes after this display in pink and red for details and formulas, respectively. To save the D-cube under a different name, from the File menu, click Save As. Enter a new name. To return to the main screen, click OK. The old D-Cube closes and you now are working on the new D-Cube with a different name.

214 Analyst

Chapter 9: D-Links
A D-Link transfers data. The target of a D-Link can be an Analyst D-Cube, a cube in a Cognos Planning - Contributor application, or a Cognos Finance dimension. Where a D-Cube is the target, the source may be another D-Cube, a cube in a Contributor application (p. 276), a dimension in Cognos Finance (p. 285), an ASCII file, an ODBC database (p. 297), or a Cognos package (p. 218). Where the target of the D-Link is a Contributor cube, certain restrictions apply and the source can only be a D-Cube or another Contributor cube. Where the target of the D-Link is a Cognos Finance dimension, the source can be an Analyst D-Cube, or a Contributor cube. Where the source of the D-Link is a Cognos Finance dimension, the target can be an Analyst D-Cube, or a Contributor cube.

Note: Contributor or Cognos Finance must be installed to use them as a target or source of data in an Analyst D-Link. To use a Cognos package as a source, you must first create a model in Framework Manager and publish the model, or elements of it as a package. When you create a D-Link, you specify how the dimensions of the source and the target correspond. Analyst is ODBC enabled, so a D-Link can import data from any source for which an ODBC driver is available, for example, Microsoft Access, Excel, and databases such as Oracle and SQL Server. You can import data in ODBC databases directly into the D-Cube because the ODBC driver presents database data in a strictly defined format. When you import data from an ASCII file, you must first create a file map (p. 731) for the ASCII file to define how the file has been structured, for example, tab separated, and how the data in the ASCII file correspond to the dimensions in the D-Cube. You do not need to open a D-Cube to update the data in it with a D-Link. However the run D-Link icon on the toolbar is only operative if a D-Cube or D-link is open. The D-Link only transfers data when the D-Link is run. There are various ways to run a single D-Link or a batch of D-Links in a specified order. You must run batches of D-Links to update your model when external data or your assumptions change. You can execute batches of D-Links using the D-Links Update list, or using macros. D-Links for which the source is a D-Cube can be run inversely to transfer the relevant data from the target to the source. You can drill down on D-Cube data that was imported by saved D-Links. This displays the original source data, regardless of its source. You can run special lookup and accumulation D-Links to reorganize your data in D-Cubes that contains D-List formatted dimensions (virtual dimensions).

User Guide 215

Chapter 9: D-Links

The D-Link Dialog Box

When you open a D-Link that has been saved, the source and target names are displayed, and their dimensions are listed in the dimension names section. Source and target dimensions may be paired together or left unpaired. Paired dimensions appear above the dividing line in the dimension names section and are connected with a pairing indicator, which indicates the pairing mode - either match descriptions (p. 233) or allocation. You can break the connection between paired dimensions, or change the pairing mode by clicking the pairing indicator. Unpaired dimensions appear below the dividing line. To view additional details of a D-Link definition, select a dimension by clicking its name. The items of the selected dimension are listed in the Dimension Items area of the D-Link dialog box. When you select an unpaired dimension, you see all items within that dimension and a separate table showing any items that have been selected from that dimension. When you select a paired dimension, the dimension it is paired with is also selected, and the dimension items section displays full details of the pairing. Initially, no dimension is selected, so the Dimension Items area is empty. The D-Link lists only unique dimension item names in the Dimension Items area. D-Lists cannot contain duplicate item names, so you will see all the D-List items in D-List order. The dimensions of an external source relates to a column in an ASCII file or a field in an ODBC database where the same item name may appear in many records (rows). The D-Link will display only the unique names, in the order in which they appear in the ASCII file or database. In either case, you may cut a subcolumn from the item names that may reduce the number of items displayed (to those which are unique within the subcolumn). In this case the D-Link only displays the first unique instance of that item. For example if you have two items A0023 Apples and A0024 Apples, and the first four characters are used in the cut, data would only be transferred to the A0023 Apples item. If these items are the source, the data in both these items would be aggregated together with the data for any other items beginning A002 and transferred to the target specified in the D-Link. When you click a dimension from an external source, Analyst will read the entire source file in order to get an up-to-date dimension item listing. With large source files you will experience a short delay while the source data is read.

Dimensions and D-Lists

The dimensions of a D-Cube are defined by the D-Lists included in the D-Cube. In a completed D-Link, the D-Lists of a D-Cube are not necessarily shown in D-Cube order. Paired D-Lists move above the dividing line in the order in which they were paired. A filemap is used to define the dimensions and data values of an ASCII file, and can have single or multiple columns. The ODBC driver effectively defines the dimensions of an ODBC database. When describing D-Links, the term dimensions will generally be used, as the D-Link is able to treat D-Lists and the dimensions of an external data source in much the same way. The term, D-Lists will only be used when a particular comment or option applies only to D-Lists. There are important differences between D-Links that use an external source and D-Links which have a D-Cube as the source.

216 Analyst

Chapter 9: D-Links In addition to normal dimensions, a D-Cube may have virtual dimensions, which are introduced when one or more of the D-Lists making up a D-Cube contains D-List formatted items. All D-Lists used as format D-Lists appear as virtual dimensions when the D-Link lists the dimensions of a D-Cube. Virtual dimensions are readily distinguished in the D-Link as the D-List name is enclosed in brackets [ ]. In normal D-Links, any virtual dimension can simply be ignored (left unpaired and no selection made). You only need to concern yourself with them if you are creating special lookup or accumulation D-Links.

Create D-Links
A D-Link is created in the following stages: Steps Select New D-Link from the menu (p. 217) Select a source and a target for the D-Link (p. 217) Pair source and target dimensions (p. 219) Select the required items from unpaired dimensions (p. 219) Change optional settings as required (p. 220) Name and save the D-Link (p. 220) These steps describe how to create a regular D-Link using a D-Cube as the source. You can also use the following as the source: mapped ASCII files (p. 731) ODBC (SQL) (p. 299) Data, Contributor data, Cognos Finance data, and a Cognos package. If you wish to create a lookup or accumulation D-Link, then you must specify the type before pairing source and target dimensions, because virtual dimensions do not appear when creating regular D-Links.

Use D-Cube as Source and Target

Steps
1. From the File menu, click New, D-Link. 2. Click Source. 3. Select D-Cube from the menu. 4. In the D-Cube Select dialog box, select a D-Cube. 5. Click OK. The D-Cube is displayed, and its dimensions are listed. 6. Click Target. 7. In the Select D-Cube dialog box, select a D-Cube.

User Guide 217

Chapter 9: D-Links 8. Click OK. If both the source and the target for the D-Link are D-Cubes, and one D-List is common to both the source and the target, these D-Lists are paired automatically using match descriptions. If required, you can change to an allocation table pairing, or break the connection by clicking the pairing indicator.

Use Cognos Package as Source in a D-Link

You may use a Cognos package as the source in a D-Link. After you pair your dimensions, you will need to specify a temporary location for the data to be stored. Note: You must first create a model in Framework Manager and publish the model, or elements of it as a package before you can use a Cognos package as a source in a D-Link.

Steps
1. Open the target D-Cube you wish to import the data into. 2. From the File menu, click New, D-Link. 3. Click Source. 4. Click Cognos Package. 5. Select a package from the drop box. 6. Select a Query Subject. 7. Select the available Query Items in the Query Subject and move them to the Selected Query Items pane. 8. Select the Display preview of selected query item check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. Click OK. The Query Items are brought into the D-Link. 9. Click Mark Data to select the columns containing the data. 10. Pair the dimensions. 11. From the D-Link menu, click Options. In the Cognos Package - Alternative temporary data storage path area, browse to a temporary location in which to store the import data. If you do not specify a location, Analyst will default to the location of the Filesys.ini file. If you specify a different default location, ensure that it is accessible and writable from all Analyst clients and Planning servers. You can also specify the temporary data storage default location before creating your D-Link. From the Tools menu in Analyst, click Options and select the General tab. Under D-Link Temporary Data Storage, you can browse to a custom default location. 12. When you have finished pairing the dimensions, from the D-Link menu, click Execute. The data is imported using the Cognos package. 218 Analyst

Chapter 9: D-Links 13. Save and close the D-Link.

Pair Source and Target Dimensions

You specify how the dimensions of the source and target correspond by pairing source and target dimensions. D-Lists that appear in both D-Cubes are already matched. If there are unmatched items, you will have to pair them.

Steps
1. Click a source dimension. The D-List items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 2. Click Ctrl + a target dimension to which you want to pair the selected source dimension. Tip: In general, dimensions belonging to the same category should be paired. For example, timescale D-Lists should be paired and products D-Lists should be paired. However, timescale D-Lists should not be paired with products D-Lists. 3. Select either Match descriptions or Allocate items: Select Match descriptions to have matched source and target items highlighted automatically, or select Allocate items to manually pair source and target items.

Select Required Items from Unpaired Dimensions

Often you will be left with unpaired dimensions in the source and/or target. If left unspecified, the unpaired items from the source will be imported into unpaired items in the target. To avoid this, you must select the required items from unpaired dimensions.

Steps
1. Click an unpaired dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box, ready for you to make a selection of items. 2. Click Select if you want to make a selection of items. Instead of making a selection of items, you can leave the selection empty.The sum of the items is transferred into the designated target cells. 3. Double-click an item in the dimension items list to move it to the Selected items box. To select more than one item, highlight the required items in the dimension items list, and then click the arrow button pointing in the direction of the selected items list. 4. Repeat steps 1 through 3 for all remaining unpaired source and target dimensions.

User Guide 219

Chapter 9: D-Links

Change Optional Settings in D-Link

Optionally you can change various settings, which will modify the way a D-Link runs.

Steps
1. Select an execution mode from the Mode box: Fill Substitute Add Subtract Select a Dump Item option (this is only relevant when importing data from external sources).

2. Select the D-Link type: Regular - shows only real dimensions. Lookup - shows real dimensions and D-List formatted items for target dimensions. Accumulation - shows real dimensions and D-List formatted items for source dimensions.

3. Specify scaling and rounding options (from the D-Link menu, click Options).

Name and Save the D-Link

Steps
1. From the File menu, click Save. 2. Select a library in the Save D-Link As dialog box. 3. Type a name for the new D-Link 4. Click OK. 5. Before you close the new D-Link, you can give it a description and attach notes to it by clicking the File menu, and then clicking Summary Info. Any description entered will be displayed at the bottom of the Select D-Link box when opening a D-Link.

Open D-Links
Steps
1. Click the open D-Link button. 2. In the D-Link Select dialog box: Select a library.

220 Analyst

Chapter 9: D-Links Select the desired D-Link. Click OK.

Open More than One D-Link

Steps
1. From the File menu, click Library, D-Links. 2. In the Library Functions dialog box, select the appropriate library. 3. Select the appropriate D-Links. 4. Select the required D-Links in the Available Objects list, and then click the down arrow to select them. 5. Click the Open button. You can also run the D-Links, copy them, move them, rename them, print, or delete them by clicking the appropriate button, but only when the D-Link is not open. 6. When the D-Links have been opened, click Close.

Open a D-Link that Targets an Open D-Cube

Use this method if you have a D-Cube open and you want to open a D-Link that uses the open D-Cube as its target.

Steps
1. Make the relevant D-Cube the active D-Cube. 2. From the D-Cube menu, click D-Links, D-Links into D-Cube. 3. In the Select D-Link to Edit dialog box: Select the desired D-Link. lick Edit.

Open a D-Link that Uses an Open D-Cube as its Source

Use this method if you have a D-Cube open and you want to open a D-Link that uses the D-Cube as its source:

Steps
1. Make the D-Cube active. 2. From the D-Cube menu, click D-Links, D-Links from D-Cube, or click the Run D-Links button.

User Guide 221

Chapter 9: D-Links 3. In the Select D-Link to Edit dialog box: Select the D-Link you want to open. Click Edit.

Open D-Links Associated with Selected D-Cubes

Steps
1. From the File menu, click Library, D-Cubes. 2. In the Library Functions dialog box do the following: Select the appropriate library. Select the appropriate D-Cube. Click the Show objects that the selected object(s) is used by button, or right-click the selected D-Cube name, and then click Show Used By from the shortcut menu. 3. You will now see a list of Analyst objects that use the highlighted D-Cube. This will include the names of D-Links that use the D-Cube as their source or target. 4. Select the required D-Links in the list, and then click the down arrow. You can automatically highlight all D-Links that use the chosen D-Cube as either a source, target, or parameter by selecting Source or Target from the Highlight usage type list. You have the option to view specific precedents or dependents, depending on their function to the D-Cube. For example, after selecting Source as the usage type and clicking the down arrow, the source D-Links are highlighted. 5. To open the selected D-Links, click the Open button. Before opening the D-Links it may be useful to move the D-Link Library Functions dialog box so that you can see the D-Links as they are opened. 6. When the D-Links have been opened, click Close.

Run D-Links
Run a D-Link to transfer data. Messages are suppressed when executing macros that run ODBC D-Links from SQL7 as a source.

222 Analyst

Chapter 9: D-Links

Run an Open D-Link

Use this method if you have an open D-Link that you would like to run.

Step
Make the appropriate D-Link active and click the Run D-Link button. The open D-Link runs. If you have made changes to the D-Link but not saved the changes, only the saved version of the D-Link runs.

Run a D-Link Using a Specific D-Cube as its Source or Target

The D-Cube may or may not be open.

Steps
1. From the Tools menu, click one of the following: Run Source Link Run Target Link

2. In the D-Cube Select dialog box do the following: Select a library. Select a target D-Cube. Click OK.

3. If a D-Cube dialog box was active in step 1, this D-Cube is selected in the D-Cube Select dialog box. In the Select D-Link to Execute dialog box do the following: Select the D-Link to run. Click Execute.

Run a D-Link Using an Open D-Cube as its Target

Use this method if you have a D-Cube open and you want to run a D-Link that uses the D-Cube as its target. If a target D-Cube is open when a D-Link is run, only data assigned to cells within the open selection of the target D-Cube is transferred. Data assigned to cells outside the open selection is not transferred. Note: If the selection open does not contain the target area, the D-Link does not execute and an error message appears. If multiple views of the target D-Cube are open, each with a different selection, data is assigned to cells included in the open views. Only data assigned to cells outside all open views is not transferred. A target D-Cube is left open after a D-Link has run. To save the changed data you must save the D-Cube.

User Guide 223

Chapter 9: D-Links If a D-Link is run into a closed D-Cube, all data assigned by a D-Link is transferred to the target D-Cube. Internally, Analyst opens the target D-Cube, transfers data into it, and then saves and closes the D-Cube automatically. D-Links do not usually assign data to all cells of a target D-Cube. The selection of cells that a D-Link can affect (assign data to) is known as the target area (p. 253) for the D-Link. Opening a limited selection of the target D-Cube before running the D-Link can be used to temporarily restrict the target area for the D-Link.

Steps
1. Ensure the required D-Cube dialog box is active. 2. Click the Run D-Link button 3. In the Select D-Link to Execute dialog box, select the D-Link you want to run, and then click Execute. D-Links run in this manner will only update data within the open selection of the target D-Cube.

Run D-Links with the Source D-Cube Open

For D-Links that use an open D-Cube as their source when a D-Link is run, data from the open selection of the source D-Cube is transferred in preference to the saved data in the source D-Cube. Data outside the open selection of the source D-Cube is taken from the saved D-Cube as normal. If multiple views of the source D-Cube are open, each with a different selection, data is taken from all open views. Only data excluded in any open view is taken from the saved version of the D-Cube. If the source D-Cube is completely open, all data is taken from the open version of the source D-Cube. Of course, this only effects the data transferred by the D-Link when the open selection of the source D-Cube contains different data than the saved version.

Experiment with the source D-Cube

The behavior described above can be useful if you want to make experimental changes to data in the source D-Cube, then feed the changed data on to other D-Cubes to observe the effect, without having to make the changes permanent. Note that you will have to open these other D-Cubes before you transfer data into them if you want to be able to undo your changes. You could change data in the source D-Cube manually. You could also change the data by running experimental D-Links into the source D-Cube. For example, you could open D-Links which target this source D-Cube, modify them and then run them without saving them. To undo your changes you would simply close the D-Links without saving them, or reset them to the saved versions by clicking Reset from the File menu. You can also change data in the open source D-Cube by modifying the D-Lists of the D-Cube and implementing rather than saving the modifications. For example, you could change formula in one of the D-Lists of the source D-Cube, implement the changes (using the menu command Implement) , then transfer the changes on to other open D-Cubes to observe the effect. To undo your changes,

224 Analyst

Chapter 9: D-Links close all affected D-Cubes without saving them. You can also reset any D-Lists with implemented changes by clicking Reset from the File menu. Remember that you cannot experiment in this way with adding, deleting or substituting D-Lists in the source D-Cube. These changes to a D-Cube are immediately saved and cannot be reset.

Run D-Links with the Source D-Cube Open with a Limited Selection
Data within the open selection of the source D-Cube is taken from the open version of the source D-Cube. Data outside the open selection of the source D-Cube is taken from the saved version of the source D-Cube.

Run Update D-Links in a Single D-Cube (Manually)

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click D-Links, Update. 3. Click Run All. You can also run the update D-Links using the macro command @DCubeUpdate.

Run Batches of D-Links Using Library Functions

You can create a selection of D-Links in the D-Cube Library Functions dialog box using the dependent tracing facilities, and then run the selected D-Links in order.

Steps
1. From the File menu, click Library, D-Cubes. 2. In the D-Cube Library Functions (p. 301) dialog box do the following: Select the D-Cube you wish to update. Click the Show objects that the selected object(s) is used by button. Make your selection from the Highlight Usage Type list. You have the option to view specific precedents or dependents, depending on their function to the D-Cube. Select the desired D-Links in the Objects Using D-Cube dialog box.

3. Click the Select button. When you select a new item, it is added at the bottom of the selected items list (you cannot reorder items in the selection list). When you run the D-Links, they will be run in the order they appear in the selected items list, so it is important that you select the D-Links in the correct order. Selected D-Links can be reodered using the arrows to the right hand side of the box.

User Guide 225

Chapter 9: D-Links 4. Click the Run button. If you want to run additional D-Links targeting different D-Cubes, you can run those selected so far, deselect them and repeat steps 2 to 4 for another D-Cube. 5. When all required D-Links have been run, click Close.

Memory Considerations
If you are experiencing memory problems when running a D-Link then consider use of the slice update facility which allows the D-Link to be run in smaller stages updating one slice of the target at a time. This facility is available for D-Links which target analyst or for D-Links which target contributor. For more information about the slice update facility, see @SliceUpdate (p. 700).

Open a limited selection from a D-Cube

Whenever a D-Cube is opened in Analyst, details of the base data and the calculations in the D-Cube are loaded into memory. Therefore, the memory available in your computer limits how much of the D-Cube may be opened. If you open only a limited selection of a D-Cube, less memory is required. The memory required to open a selection of a D-Cube is not directly determined by the selection you make from the D-Cube. If you include any formula items in your selection, then internally, Analyst may have to open an expanded version of your selection. The memory required to open and recalculate a D-Cube is not determined by the selection you have made from the D-Cube, but by the expansion of this selection.

What is an expanded selection?

When you open a limited selection from a D-Cube, only the items you selected are displayed in the D-Cube dialog box. If you have included formula items in your selection, however, an expanded selection may be opened internally, so that the selected formula items can be recalculated and broken back properly. If a basic selection includes formula items, the expanded selection will also include all the items on which the selected formula items depend (either directly or indirectly). For example, consider a Months D-List that contains twelve detail items (Jan, Feb, Mar, and so on), four quarterly totals (Q1 = Jan + Feb + Mar, and so on), and one full year total (Full Year = Q1+Q2+Q3+Q4). If you open a D-Cube containing this D-List and select only Q1 from MONTHS, the expanded selection will include Q1 and Jan, Feb, and Mar. If you select only Full Year, the internal expanded selection will include all items in the MONTHS D-List. Remember that Analyst does not save calculated data in the D-Cube when it is closed; data in formula items is only recalculated when required.

What is opened when a D-Link is run?

When a D-Link using a D-Cube as its source is run with the source D-Cube closed, Analyst opens the source D-Cube internally to read the data from it.

226 Analyst

Chapter 9: D-Links If the D-Link picks up only detail data from the source D-Cube, a basic selection of items, determined by the D-Link definition, is opened. The basic selection includes all items assigned by match descriptions or an allocation table, and all items selected from unpaired source D-Lists. However, if the D-Link imports calculated numbers from the source D-Cube, the selection of items opened will be the expansion of the basic selection. If the source D-Cube is fully open when the D-Link is run, Analyst does not need to open it internally as all the required data can be taken from the open version of the D-Cube. If the source D-Cube is open with a limited selection when the D-Link is run, Analyst may need to open an additional selection internally if all data transferred by the D-Link is not found in the open selection. If the target D-Cube is closed when the D-Link is run, Analyst opens the target D-Cube internally, transfers data into it, saves and closes the D-Cube automatically. The portion of the target D-Cube that Analyst needs to open internally is the expansion of the D-Link's normal target area. The target area includes target items matched by match descriptions (p. 233), target items with entries in a local allocation table (p. 242), and items selected from unpaired target D-Lists (p. 231). If the target D-Cube is open when a D-Link is run, data is only assigned within the open selection of the target D-Cube. Data assigned to cells outside the selection you have opened is not transferred, even if these cells are within the internal expanded selection. So when you run a D-Link into a selection from an open D-Cube, nothing extra is opened and no expansion takes place.

Run Batches of D-Links using Macros

You can use the following macro commands to run batches of D-Links: @DLinkExecute (p. 665) - runs one D-Link @DLinkExecuteList (p. 666) - runs a series of D-Links in order @DCubeUpdate (p. 696) - runs the update D-Links list for one D-Cube @DLinkExecSel (p. 664) - runs a D-Link into a limited selection of a target D-Cube

When you use either @DLinkExecute or @DCubeUpdate to run D-Links, the D-Links behave exactly as if they had been run manually. For example, when the @DCubeUpdate command is run, the target D-Cube may be closed, fully open, or open with a limited selection. If closed, data changed in the target D-Cube is saved automatically at the end of the update. If open with a limited selection, only the open selection of the target D-Cube will be updated.

Tun an Inverse D-Link

Any D-Link for which the source is a D-Cube can be run inversely, that is, it can transfer data from the target to the source. Note: You cannot use drill down to trace data that has been transferred by an inverse D-Link. Also remember that a D-Link run inversely does not have exactly the same the reverse effect of the D-Link run normally. To establish what a D-Link will do with data when run inversely, look at the normal D-Link definition and imagine that the source and target D-Cubes have been exchanged, while the rest of the D-Link definition is left unchanged. User Guide 227

Chapter 9: D-Links Match descriptions (p. 233) pairings are preserved with the source and target D-Lists exchanged. Any subcolumn cut (p. 259) from a D-List is preserved. The case-sensitive setting is not changed. The dump item setting is only relevant when importing data from external sources. Allocation table pairings are preserved. The source and target D-Lists and the source and target columns in the allocation table are exchanged. Any subcolumn cut from a D-List is preserved. The case sensitive setting is not changed. The dump item setting is only relevant when importing data from external sources. Unpaired source and target D-Lists (p. 231) are exchanged. The selection of items made for a D-List is preserved. The D-Link execution mode (p. 252) is unchanged. The scaling option is reversed; data transferred by the inverse D-Link is scaled by the inverse of the scaling factor set for the forward D-Link. For example, if the scaling factor (p. 257) is set to 10 (divide by ten), then the inverse D-Link will use a scaling factor of 0.1 (divide by a tenth) . The rounding option (p. 257) is unchanged; data transferred by the inverse D-Link is rounded according to the setting in D-Link options. The D-Link dump option is only relevant when importing data from external sources.

Note: Special rules apply when running accumulation D-Links inversely; the inverse accumulation D-Link will perform a break back allocation over the source data. (Lookup D-Links should not be run inversely at all). See the Lookup and accumulation D-Links section for more information.

Steps
1. Open a target D-Cube. The D-Cube which is the target for the D-Link as defined, and the source for the inverse D-Link. 2. With the target D-Cube dialog box active, click the Run D-Link button. 3. From the list, select the D-Link you want to run, and then click Inverse. Be sure you have selected the correct D-Link. When you click Inverse, the selected D-Link is run inversely - data is transferred and the source D-Cube is saved automatically. If you have the source D-Cube completely open when you run a D-Link inversely, you can save the data transferred to the source D-Cube after the D-Link has run. You can also run D-Links inversely using a macro. The @DLinkExecInv command runs one D-Link inversely. It always runs the D-Link as it is found when the macro is run, not as it was when the macro was created. The D-Link to run inversely is identified by the macro's only parameter: DLink.

Exchange Source and Target D-Lists by Running D-Links Inversely

When a D-Link is run inversely, the source and target D-Lists are exchanged. Source and target D-Lists are treated differently by the D-Link in some respects: Exchanging them can sometimes give unexpected results. The differences you must consider are listed below.

228 Analyst

Chapter 9: D-Links

Many-to-one and one-to-many allocation tables

A many-to-one local allocation table (p. 247) sums the data in multiple source items and assigns the total to a target item. However, when the source and target for a many-to-one allocation table are exchanged, the data in the target item is taken and assigned to each source item. The data in the target item is not split up and allocated over the source items, like a break back. Similarly, a one-to-many local allocation table (p. 247) takes data from one source item and assigns it to multiple target items. When the source and target for a one-to-many allocation table are exchanged, data from the multiple target items is summed, and the total assigned to the source item.

Unpaired dimensions
In an unpaired source D-List (p. 231), data is taken from all items selected and summed. In a unpaired target D-List (p. 231), data is assigned to each of the items selected.

Cut subcolumns
If multiple items in a source or a target D-List are identical within a subcolumn (the subcolumns were cut (p. 259)), only a single instance of the cut-down item name is displayed in the item names list. The cut-down name may be matched by match descriptions (p. 233) or used in an allocation table entry. In a source D-List, data from all items that match the cut-down name is summed. In a target D-List, data is assigned to the first item in the D-List that matches the cut down name.

Formula items and match descriptions

Match descriptions (p. 233) will take data from formula items in a source D-List, but will not assign data to formula items in a target D-List. Thus, when the source and target for a match descriptions pairing are exchanged, the set of matching items may be different than the original set of matching items. For example, the item, Q1, appears as a formula item in the D-List, Months, and as a detail item in the D-List, Quarters. Match descriptions will match the Q1s if Months is the source D-List, but it will not if Months becomes the target D-List.

Case sensitive option

When the case sensitive option is not selected, one allocation table entry may correspond to multiple D-List items, and match descriptions may match multiple D-List items at a time. By default the Case Sensitive option is on. Clear the Case Sensitive check box if you want match descriptions to ignore capitalization in the source item names. Typically, this is used when there are inconsistencies in the capitalization of source item names that you want the D-Link to ignore. When the Case Sensitive check box is selected, a highlighted item in the source will only have one matching item in the target. If cleared, there may be many source items highlighted that all match one target item. Data from all matching source items is summed and assigned to the matching target item.

User Guide 229

Chapter 9: D-Links The D-Link lists only unique item names. This is always case sensitive regardless of the Case Sensitive option. In a source D-List, if match descriptions matches more than one source item with one target item, or more than one item corresponds to one source allocation table entry, then data from all matching source items is summed. In a target D-List, if match descriptions matches more than one target item with one source item, or more than one item corresponds to one target allocation table entry, then data from the source item is assigned to the first matching item in the target D-List.

Dimensions
A D-Cube is made up of dimensions, which are D-Lists, or virtual dimensions.

Virtual Dimensions
In addition to normal dimensions, a D-Cube may have virtual dimensions. Virtual dimensions are introduced when one or more of the D-Lists making up a D-Cube contains D-List formatted items. When Regular is selected as the D-Link type, no virtual dimensions show in the D-Link editor. To view any virtual dimensions in the source cube, set the D-Link type as Accumulation. To view any virtual dimensions in the target cube, set the D-Link type as Lookup. In normal D-Links, any virtual dimension can simply be ignored (that is, left unpaired and no selection made). You only need to concern yourself with them if you are creating special lookup or accumulation D-Links. For information about lookup and Accumulation D-Links. Note: You cannot cut a Subcolumn when pairing virtual dimensions.

Dimensions and D-Lists

When describing D-Links the term dimensions is generally used, as a D-Link is able to treat D-Lists and the dimensions of an external data source in much the same way. The term, D-Lists is only used when a particular comment or option applies only to D-Lists.

Unvisited Dimensions
After selecting the source and target D-Cubes in a new D-Link, all dimensions are considered unvisited (not yet paired or selected). When you select an unvisited dimension in a new D-Link, the dimension items are displayed in the same way as for an empty selection. Unvisited dimensions are assumed to be empty selections; so when you are creating a D-Link, ensure you have made the appropriate selection from all unpaired dimensions. Remember that if a dimension is added or deleted from a D-Cube or external source (for example, in an ASCII file new columns may appear and existing columns may be removed or skipped), then D-Links using the D-Cube (or external source) are likely to have new unvisited dimensions. If a dimension is added, it will be unvisited in D-Links. If a dimension is deleted, any dimension to which it was paired will be unvisited.

230 Analyst

Chapter 9: D-Links Unless you edit the D-Links, unvisited dimensions are considered empty selections. If the empty selection is in the source, all detail items are aggregated. If the empty selection is in the target, all detail items are populated.

Unpaired Dimensions
Usually, you will be left with unpaired dimensions in the source and/or the target of a D-Link. It is recommended that you make a selection (p. 232) of the required items from unpaired dimensions.

Unpaired Source Dimensions

From an unmatched source dimension you should make a selection of the item (or items) that contains the data you want to be transferred in a D-Link. If you select more than one item, the data in all selected items is summed when the D-Link is run. Note: You do not have to select any items. An empty selection implies use all items. If the source dimension is a D-List, data is taken from all detail items only. If you want to take data from formula items, you will have to explicitly select them. If the source dimension relates to a column in an ASCII file, empty records may be found in this column. If the selection of source items is left empty, data in rows identified by a blank item will be imported. You cannot include a blank item in the selected items list. If the source dimension is not a D-List, the items selected are not linked to the source item names. If a source item is renamed or an item disappears, the original entry in the selected items list is not updated or removed. Note: In an accumulation D-Link there are two distinct types of unpaired source dimensions: The source Lookup D-List itself which should never be left with an empty selection, and any other remaining unpaired dimensions which will often be left unvisited.

Unpaired Target Dimensions

From an unpaired target D-List you should make a selection of the item (or items) into which the data should be transferred in a D-Link. If you select more than one item, the data is copied into each selected item (not divided and apportioned across the target items). You do not have to select any items. An empty selection implies target all detail items. If you want to target formula items, you will have to explicitly select them. When a D-Link targeting formula items is run, a break back will be performed in the target D-Cube as if the data had been entered manually in the D-Cube. One break back can change a large amount of data! You should not target formula items accidentally. Remember, if you run a D-Link into a closed D-Cube, the changed data is saved automatically. You can target a formula item and some of its dependent detail items. In this case data is first transferred to the detail items, then these items are held while a break back is performed as data is transferring to the formula. Note: In a Lookup D-Link there are two distinct types of unpaired target dimensions: The Lookup D-List itself which should never be left with an empty selection and any other remaining unpaired dimensions which will often be left unvisited.

User Guide 231

Chapter 9: D-Links

Empty Selections
In a D-Link, empty selections can be very useful, as they adapt to changes in the dimension item listing. For a D-List, all detail items are used (or targeted) even if new detail items have been added since the D-Link was defined. For other dimensions, all source items are used even if items have been renamed or added. When a source dimension relates to a column in an external source, it is important to remember that the empty selection will accept all entries found in this column.

The DATA dimension and @Count

When a Map is used as the source for a D-Link, the columns marked Use as data become the items of one dimension named DATA. The D-Link always includes an item named @Count in the DATA dimension. When a DATA dimension is left unpaired in the D-Link, the empty selection will sum all items except @Count.

Make a Selection of Items in a D-Link Steps

1. Open an appropriate D-Link. 2. Click an unpaired source or target dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 3. Click Select to display the selected items list. 4. In the Select items box do the following: Double-click an item in the dimension items list to add to the selected items list. To add more than one item, select the required items in the dimension items list, then click the right arrow. You can highlight adjacent items by dragging or by holding shift in conjunction with end, home or arrow. You can highlight non-adjacent items by holding Ctrl and clicking.

5. To remove an item from the Selected items box, double click the item name. To remove more than one item, highlight the required items and click the left arrow. 6. Notice that selected items are not removed from the dimension items list.

Cancel a Selection of Items in a D-Link

In a D-Link, if you want to pair a dimension from which a selection of items has been made you must first cancel the selection of items. You might also cancel a selection of items in order to use an empty selection (p. 232).

Steps
1. Open an appropriate D-Link. 232 Analyst

Chapter 9: D-Links 2. Click the unpaired source or target dimension. 3. Select an item from the Selected items box. 4. Click the left arrow. 5. Repeat as necessary. When emptied, the selection list does not immediately disappear, but when you return to the dimension it will have been removed.

Match Descriptions
In a D-Link, Match Descriptions automatically matches source and target dimension items with the same name. In addition, Match Descriptions can be used to perform an allocation by date. For information about specifying a match description pairing, see "Create a Match Descriptions Pairing" (p. 233).

How Match Descriptions Pairs Data

When you first choose a Match Descriptions pairing or open a D-Link and look at an existing Match Descriptions pairing, the item names in the source and the target dimensions are compared and the matching items are highlighted. When the D-Link is run this comparison is made again and data from each highlighted source item is assigned to the matching target item. The key benefit of the Match Descriptions pairing is that it updates automatically. The D-Link will always assign data according to what matches at the time it is run, even if items in the source or target have been added, deleted, or renamed. By default, Match Descriptions will not assign data to formula items in a target D-List unless Match Calculated Target Items is selected. This exception is made to avoid unnecessary break backs. It is not possible to exclude individual matching items from the match descriptions allocation. If you want to do this you will have to use an allocation table. When you use an external source for a D-Link, the source dimensions relate to columns in an ASCII file or fields in an ODBC database, where the same item name may appear in many rows (records) . The D-Link will display only the unique names in the order in which they appear in the ASCII file or database. When the D-Link is run, Match Descriptions takes the data from all matching records, sums it, and assigns the total to the matching target item.

Create a Match Descriptions Pairing

You cannot pair a dimension that is part of an existing pairing; you must first break the existing connection. To do this, right-click the pairing indicator and select Break Connection.

User Guide 233

Chapter 9: D-Links You cannot pair an unpaired dimension from which a selection of items has been made either; you must first clear the selected items list (p. 232).

Steps
1. From the File menu, click New, D-Link. 2. Click Source and select a source. 3. Click Target and select a target D-Cube or Contributor cube. 4. Click a source dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 5. Click Ctrl + target dimension that you want to pair with the selected source dimension. Both the source and target dimension names are now selected, and the items of both dimensions are displayed in the D-Link dialog box. 6. Click Match descriptions. The paired dimensions move above the line, joined by the match descriptions pairing indicator. Click the pairing indicator to change the pairing mode or break the connection. The matching source and target items are highlighted. If required, you can change the case sensitive option, match calculated target items, select a dump item, and cut subcolumns from the source and/or target dimensions.

Case Sensitivity
By default the Case Sensitive option is on. Clear the Case Sensitive check box if you want match descriptions to ignore capitalization in the source item names. Typically, this is used when there are inconsistencies in the capitalization of source item names that you want the D-Link to ignore. When the Case Sensitive check box is selected, a highlighted item in the source will only have one matching item in the target. If cleared, there may be many source items highlighted that all match one target item. Data from all matching source items is summed and assigned to the matching target item. The D-Link lists only unique item names. This is always case sensitive regardless of the Case Sensitive option. For example, the items, ITEM1 and item1, will both be listed whether the Case Sensitive check box is selected or cleared. Tip: While it is not recommended, you may include D-List item names that are duplicates except for capitalization (for example, ITEM1 and item1). If a D-List containing such duplicate names appears in the target and the Case Sensitive check box is cleared, then all of these items will be highlighted, but match descriptions will only assign data to the first highlighted item.

234 Analyst

Chapter 9: D-Links

Match Calculated Target Items

You can use match descriptions to match calculated totals and detail items in a D-Link. Matching formulas triggers a break back in the target D-Cube so be cautious.

Steps
1. From the File menu, click New, D-Link. 2. Click Source and select a source. 3. Click Target and select a target D-Cube. 4. Click a source dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 5. Ctrl+Click the target dimension that you want to pair with the selected source dimension. Both the source and target dimension names are now selected, and the items of both dimensions are displayed in the D-Link dialog box. Note: If the source data contains items which match to both the detail and the calculated items in the target, and the target cube is not all zero, the calculation engine ignores the imported data for the totals and only keeps the imported data for the details. This could mean that the D-Link will not transfer data as expected. To avoid this potential problem - set the D-Link to Substitute mode, or use an allocation table to ensure that only calculated items are matched. 6. Click Match description. The paired dimensions move above the line, joined by the match descriptions pairing indicator. Click the pairing indicator to change the pairing mode or break the connection. The matching source and target items are highlighted. If required, you can change the case-sensitive option, select a dump item, and cut subcolumns from the source and/or target dimensions. 7. Select the Match Calculated Target Items check box. This matches calculated totals in the target D-Cube in addition to detail items. Note: If a contributor cube is the target of the D-Link then this option is not relevant as only detail items may be targeted in the target lists.

Allocation
When choosing to allocate items in a D-Link there are three options available Local Allocation tables (p. 242) Loaded Allocation tables (p. 248) D-Cubes used as allocation tables (p. 249)

User Guide 235

Chapter 9: D-Links The behavior of D-Links is the same regardless of the type of allocation table used, but there are some minor functional differences between the three options. Subcolumns can only be cut in a local allocation table. Wildcard characters can only be used in a local or loaded allocation tables. Local Allocation table entries may only contain items found in the source and target D-Lists (unless subcolumns are cut) in a local allocation table. Local allocation tables cannot be shared by many D-Links. Sign changing per entry is only supported in the A-Table. You cannot create mixed many-to-one and one-to-many allocations using D-Cube data allocations.

Maintain Allocation Tables

The most significant difference between the three allocation table types is how the allocation tables are maintained. Local allocation tables are maintained manually. There are also options provided for importing allocation table entries from external sources, including mapped ASCII files, two-column delimited ASCII files, ODBC databases, and Cognos packages. However, you cannot create a D-Link to refresh the allocation table entries from these external sources. In saved A-Tables, you can import the source and target items, but not the allocation table entries from external sources, including Mapped ASCII files, delimited ASCII files, ODBC databases, and Cognos packages. If you import source and/or target items from a mapped ASCII file, you can refresh the import. There are options provided to help with updating the allocation table entries. For example, the Restrict to unallocated and Show allocated items options. D-List formatted data in a D-Cube can be used as an allocation table in many D-Links. Different D-Links can use different selections of one D-Cube, so one D-Cube can effectively contain many allocation tables. You can paste the allocation table data from the clipboard, or import it from an external source using a D-Link. You can run the D-Link multiple times to refresh the allocation table data, and then drill down on the allocation table data.

Allocation Table Menu Options

By selecting Allocation Table from the D-Link menu, you can use a number of different Allocation Table options, including: Load (p. 240) Save (p. 243) Match Descriptions (p. 233) Import from a file (p. 243), or from an ODBC or Cognos package source Use D-Cube Data (p. 250)

236 Analyst

Chapter 9: D-Links Use Saved Selection (p. 250)

How Allocation Tables Assign Data

Each entry (row) in the allocation table defines the correspondence of a source and a target item. You can create one-to-one allocations, many-to-one allocations (data from many source items is summed and assigned to one target item), and one-to-many allocations (data in one source item is assigned to many target items). You can mix all three types of allocation in a single allocation table. When the D-Link is run, data is transferred according to the allocation table entries. Suppose a local allocation table is set up as follows:

Source D-List
S1 T1 S2 T2 S3 T3 S4 T4 S5 T5 S Total T Total

Local Allocation table entries

S1

Target D-List
T1

S2

T2

S3

T2

S4

T2

S5

T3

S5

T4

S5 When the D-Link is run: Data from S1 is assigned to T1.

T5

Data from S2, S3, and S4 is summed and the total allocated into T2. Data from S5 is allocated into T3, T4, and T5 (not apportioned across T3, T4, and T5).

When you use an external source for a D-Link, the source dimensions relate to columns in an ASCII file or fields in an ODBC database, where the same item name may appear in many rows (records) . The D-Link will display only the unique names, in the order in which they appear in the ASCII file or database. When the D-Link is run, the allocation table takes the data from all records for which an entry exists in the allocation table, sums it, and assigns the total to the target item. User Guide 237

Chapter 9: D-Links

Example
The source dimension in the allocation table above might relate to an ASCII file containing these two columns:

Item
S1 S1 S2 S2 S3 S3 S4 S4 S5 S5

Value
1 2 3 4 5 6 7 8 9 10

When the D-Link is run, data is assigned like this: (1+2) will be assigned to T1. (3+4 + 5+6 + 7+8) will be assigned to T2. (9+10) will be assigned to T3, T4, and T5.

Navigate Around an Allocation Table

The allocation table is simply a grid with two columns and as many rows as there are allocation table entries in a D-Link. It performs like any other grid in Analyst, similar to D-Cubes. Activate a cell in the allocation table by clicking it. Move the active cell around using standard navigation keyboard shortcuts:

Shortcut
Arrow keys Home

Description
Move the active cell in the direction indicated Makes the first cell in the current row active

238 Analyst

Chapter 9: D-Links

Shortcut
End Ctrl+Home Ctrl+End Page Down Page Up

Description
Makes the last cell in the current row active Makes the first cell in the grid active Makes the last cell in the grid active Moves the active cell down one page Moves the active cell up one page

To select a range of cells in the allocation table grid, drag the first cell to the desired destination. You can also select a range of cells by holding the shift key and pressing the arrow keys above. For example, to highlight the entire allocation table: press Home, then press Shift+Ctrl+End. Tip: To find which source dimension items match an allocation table entry, click a cell in the source side of the allocation table, and the corresponding item from the source dimension is highlighted. If more than one source item matches a source allocation table entry, if the entry contains wildcard characters or the case sensitive option is turned off, all matching items are highlighted. Wildcard characters of * and ? are allowed in a filter or an allocation table. Use a question mark (?) to represent any single character. Use an asterisk (*) to represent any series of characters. Click And to show items that satisfy both criteria. Click Or to show items that satisfy either criteria. If Match Case is selected, it will further refine the filter to match on capitals or small letters. The Name box can be set using the equal symbol (=), or the not equal symbol (<>). Use the equal symbol (=) to show items that meet the criterion. Use the not equal symbol (<>) to exclude items that meet the criteria. For example, if you have an item named P01, and you enter P01*, it will search for anything beginning with the characters P01. If you enter P?????????, it means search for any D-List item that starts with a P and is ten characters long (including spaces). By default the Case Sensitive option is on. Clear the Case Sensitive check box if you want match descriptions to ignore capitalization in the source item names. Typically, this is used when there are inconsistencies in the capitalization of source item names that you want the D-Link to ignore. When the Case Sensitive check box is selected, a highlighted item in the source will only have one matching item in the target. If cleared, there may be many source items highlighted that all match one target item. Data from all matching source items is summed and assigned to the matching target item. The D-Link lists only unique item names. This is always case sensitive regardless of the Case Sensitive option.

User Guide 239

Chapter 9: D-Links

Load an A-Table into a D-Link

You can load any A-Table into a D-Link. Its source and target dimensions do not need to be the same as the dimensions it is pairing in the D-Link. As long as some items in the paired dimensions match the allocation table entries in the A-Table the D-Link will run. If no items match, you will see a "No items match" message.

Steps
1. Open a D-Link. 2. Select an allocation table pairing. 3. From the D-Link menu, click Allocation Table, Load. 4. In the A-Table Select dialog box do the following: Select a library. Select the required A-Table. Click OK.

The D-Link dialog box will display the A-Table library and name. You can also create a new A-Table by saving a local allocation table in a D-Link as an A-Table.

Steps
1. Open the D-Link and select the required allocation table pairing. 2. From the D-Link menu, click Allocation Table, Save. 3. Select a library from the list, then type a name for the A-Table. 4. Click OK.

Change to Matched Descriptions

This feature of Analyst is useful for converting an allocation table pairing within a D-Link to a matched descriptions pairing in a few easy steps.

Steps
1. Open a D-Link. 2. Click an allocation table pairing (indicated by the allocation table pairing indicator. 3. Select Change to Matched Descriptions.

240 Analyst

Chapter 9: D-Links

Change to Allocation
This feature of Analyst is useful for converting a match descriptions pairing within a D-Link to an allocation table pairing in a few easy steps.

Steps
1. Open a D-Link. 2. Click a match descriptions pairing (indicated by the match descriptions pairing indicator. 3. Select Change to allocation. 4. Pair the source items with target items using the local allocation table.

Change Dimension Items in a D-Link

Normally entries in an allocation table corresponding to D-List item names are linked to other D-List item names. If the D-List item name changes, so does the entry in the allocation table. An exception to this is when a subcolumn is cut from a D-List; the entries in the allocation table are no longer linked to the cut down item names. If the items in an external source or Contributor target change, the local allocation table will not be updated and you will have to edit it manually. If an item is deleted from a D-List, occurrences of this item name in allocation table entries are replaced with the text "Item Deleted". The allocation table will still function (providing some complete entries are left) because deleted entries are ignored. These allocation table entries are not removed automatically so that you are aware that an entry has been removed, but when you save the D-Link, you are given the option to remove these entries. Items added to D-Lists are not automatically added to any allocation table.

Other dimensions
Entries in an allocation table corresponding to items in the dimensions of a mapped ASCII file or an ODBC database cannot be linked to the dimension item names. New text in an external source is not recognized. If an item name is deleted from the item name listing, the entries in allocation tables are left unchanged. New item names are not automatically added to any allocation table.

Target Formula Items

Unlike Match Descriptions, a local allocation table (p. 242) can target formula items in a D-List without selecting Match Calculated Target Items. When a D-Link containing an allocation to formula items is run, a break back will be performed in the target D-Cube as if the data had been entered manually. There is nothing impeding your ability to target a formula item and some of its dependent detail items. In this case, data is first transferred to the detail items, then the items are held while a break back is performed on the transferred data.

User Guide 241

Chapter 9: D-Links Do not accidentally target formula items - one break back can change a large amount of data. Remember: if you run a D-Link into a closed D-Cube, the changed data is saved automatically. After a D-Link is run, the status bar at the bottom of the Analyst screen will display calculation messages. If you see "Backward" calculation messages, the D-Link has caused a break back in the target D-Cube, either because formula items have been targeted, or because formula items are held.

Local Allocation Tables (A-Tables)

Typically local allocation tables are used to define the correspondence of a small number of items (frequently just one or two). These may be one-to-one allocations, accumulations, where a source dimension does not include the required subtotal, for example, or an allocation of one source item to a distinct subset of target items. After you have defined a local allocation table, you have the option to save it as an A-Table directly from the D-Link. You can also use D-Cube data or saved selections as a basis for allocation. Often Match Descriptions (p. 233) can replace a local allocation table, but there are many cases when match descriptions is inadequate. For example: when the items will not match, even after cutting subcolumns, when targeting formula items, when performing one-to-many allocations, when you need exclude matching items from the allocation, or when you want to ensure that new items introduced to source or target dimensions are not matched automatically.

Create a Local Allocation Table Pairing

Steps
1. From the File menu, click New, D-Link. 2. Click Source and select a source. 3. Click Target and select a target. 4. Click a source dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 5. Ctrl+click a target dimension that you want to pair with the selected source dimension. Both the source and target dimension names are now selected, and the items contained in each dimension are displayed. 6. Click Allocate items. The paired dimensions are indicated by the allocation table pairing indicator. Click the pairing indicator to change the pairing mode, or break the connection. You can also choose an Allocation option, for example, loading or importing Allocation data, or using D-Cube Data. See Allocation Table Menu Options (p. 236).

242 Analyst

Chapter 9: D-Links 7. Click an item in the source. 8. Click an item in the target. 9. Repeat as necessary. If required, you can change the Case Sensitive (p. 234) option, select a Dump item (p. 256), and Cut Subcolumns (p. 259) from the source and/or target dimensions. To break the connection, click the pairing indicator and select Break Connection. You cannot pair a dimension that is part of an existing pairing; you must first break the existing connection. You cannot pair an unpaired dimension from which a selection of items has been made; you must first clear the selected items list.

Save a Local Allocation Table as a Saved A-Table Steps

1. Open a D-Link. 2. Select an allocation table pairing. 3. From the D-Link menu, click Allocation Table, Save. 4. In the Save A-Table As dialog box do the following: Select a library to which you will save the A-Table. Type a name for the new A-Table. Click OK.

Import a Local Allocation Table

You may import an allocation table from a mapped ASCII file, an unmapped ASCII file, providing it is a delimited file with exactly two columns or an ODBC database into a D-Link. Note: When you import an allocation table, all existing entries in the allocation table are removed. When importing an allocation table, all entries that correspond to D-List items must be valid D-List item names. For more information, see "Edit Local Allocation Table Entries" (p. 246).

Steps
1. Open the appropriate D-Link. 2. Select the existing allocation pairing or define a new allocation pairing. 3. From the D-Link menu, click Allocation Table, Import from File. 4. Select the required source type from the menu. 5. In the Specify allocation table dialog box do the following: Select the required source dimension and click Source.

User Guide 243

Chapter 9: D-Links Select the required target dimension and click Target. Click OK.

The allocation table entries are imported and are displayed in the D-Link dialog box.

Delete Entries in a Local Allocation Table

Steps
1. Open a D-Link. 2. Select the local allocation. 3. Select the entries to be deleted. Note: You must select the entire entry - both the source and the target column. 4. Press Delete to remove the selected entries from the allocation table. - or Right-click the selected range and select Delete Highlighted Rows, or Delete all Rows from the shortcut menu. The allocation table entries are deleted.

Use Wildcard Characters in Local Allocation Tables

If the source dimension for an allocation table is not a D-List, you can manually edit the source allocation table entries and introduce wildcard characters.

Steps
1. Open the appropriate D-Link. 2. Double-click a cell in the local allocation table, or press f2. 3. Type an asterisk ( * ) to represent any number of characters (including none) and a question mark ( ? ) to represent any single character. When you select a source entry containing wildcard characters, all the matching items are highlighted in the source dimension items list. As an example, look at the following allocation table. 612 Canada 613 Central America 614 Latin America Americas Americas Americas

This could be replaced by various one line entries.

244 Analyst

Chapter 9: D-Links

61*

Americas

61? *

Americas

61?*

Americas

?1?*

Americas

The asterisk ( * ) represents any character in that position and all remaining positions. Therefore, the asterisk ( * ) should only be used at the end of entries. For example, all of the following entries (beginning with characters 61) are assigned to Americas. 61* Latin America 61*Latin 61*Any text here Americas Americas Americas

Priority of source entries: As a result of including wildcard characters in source allocation table entries, one source item may be assigned to a number of target items. A matching source item will be assigned by the first matching allocation table entry. For example, the following allocation table means: Assign items beginning with characters 619 to UNALLOCATED. Then, assign items not already assigned and beginning with characters 61 to Americas. 619* 61* UNALLOCATED Americas

In contrast, the following allocation table means: Assign items beginning with characters 61 to Americas. This allocation table will never assign any records to UNALLOCATED. 61* 619* Americas UNALLOCATED

Suppose the source item 619 Test Market is found when the D-Link is run. It will be assigned by the first matching source entry in the allocation table. The first allocation table will assign this item to UNALLOCATED. The second allocation table will assign it to Americas. This can be a very useful feature, but you must remember to order the allocation table entries correctly. And always take care to avoid including ambiguous source entries accidentally.

User Guide 245

Chapter 9: D-Links

Edit Local Allocation Table Entries

When you create a local allocation table in a D-Link, you can only include entries for items present in the dimension at that time. If the source for an allocation table is not a D-list, you can build an allocation table with entries not yet present in the source dimension by editing lines within the local allocation table. Normally entries in an allocation table corresponding to D-List item names are linked to the D-List item names. If the D-List item name changes, so does the entry in the allocation table. An exception to this is when a subcolumn is cut from a D-List, the entries in the allocation table are no longer linked to the cut down item names. Entries in an allocation table corresponding to items in the dimensions of a mapped ASCII file or an ODBC database are not linked to the dimension item names. If the dimension item name changes, the entry in the allocation table does not update. If a dimension item disappears, the allocation table entry is not removed. As a result, you may edit source allocation table entries that correspond to dimensions other than D-Lists. To edit the contents of a cell in an allocation table, double-click the cell, or select the cell and press f2. Because these allocation table entries are not linked to dimension item names, they may contain virtually anything. If the source dimension relates to a column in an ASCII file, the column may be empty in some rows. You can include an empty source allocation table entry (an empty cell in the source column) if you want to assign data in these rows to a target D-List item. (Normally you would want them treated as dump items.) Because allocation table entries for a D-List are linked, you cannot edit entries in an allocation table corresponding to D-List item names.

Reorder Lines in a Local Allocation Table

You cannot reorder entries in a local allocation table. Each new pairing you create is introduced as a line at the end of the table. The order of entries can only influence the behavior of an allocation table when the source for an allocation table is not a D-List and wildcard characters have been used in source entries. The only way you can re-order is by deleting individual rows and recreating them at the end of the table.

Add Entries to a Local A-Table

Add a Single-Line Entry to a Local Allocation Table Steps
1. Open a D-Link. 2. Select the local allocation. 3. Click a source dimension item.

246 Analyst

Chapter 9: D-Links 4. Click a target dimension item. The allocation table entry will be added at the end of the existing allocation table.

Duplicate allocation table entries

You cannot add to an allocation table an entry that already exists. If you attempt to add a duplicate entry, the original entry is left in place.

Add Many-to-One Entries to a Local Allocation Table Steps

1. Open a D-Link. 2. Select the local allocation. 3. Drag to select source items. 4. Click one target item only. If you select more than one target item, you will not create many-to-one allocation table entries. The allocation table entries are added.

Add One-to-Many Entries to a Local Allocation Table Steps

1. Open a D-Link. 2. Select the local allocation. 3. Select one source item. 4. Select the target items. Non-adjacent items can be selected by Ctrl+clicking the items. Multiple adjacent items can be selected by dragging. The allocation table entries have been added.

Add Multiple-Line Entries to an Allocation Table Steps if the source items are adjacent
1. Open a D-Link. 2. Select the local allocation. 3. Drag to include items in the source range (or press Shift+Down Arrow). 4. Drag to include items in the target range.

User Guide 247

Chapter 9: D-Links Note: Highlight exactly the same number of source and target items. If the number of source and target items you select is different, then only some of the required entries will be added to the allocation table. 5. The allocation table entries are added. Note: Duplicate allocation table entries If you attempt to add a number of lines, some of which are duplicates, the new lines will be appended at the end of the existing allocation table, the duplicates lines are not added (the original entries are left in place).

Steps if the source items are not adjacent

1. Open a D-Link. 2. Select the local allocation. 3. Click an item in the source list. 4. Ctrl+click the remaining items in the source list. You can highlight adjacent items by holding Ctrl and dragging. 5. Drag to include items in the target list. Note: You cannot select multiple non-adjacent items from the target items list (the allocation table entries are added when you first release the mouse button in the target list). The allocation table entries are added.

Loaded Allocation Tables

Saved Allocation Tables
Saved A-Tables are used for larger allocation tables in a D-Link. You should use a shared A-Table if you want to use an allocation table in more than one link, or if you want different users' D-Links to use a centrally maintained allocation table. You can also use a large A-Table in a D-Link, even if only a subset of the source and/or target items are found in that D-Link. You may also use a saved A-Table simply to take advantage of the extra functions it offers - sign changing per line, highlighting unassigned items, and so on. For more details about Allocation Tables see "Local Allocation Tables (A-Tables)" (p. 242). To edit an A-Table while in the target D-Link, in the D-Link editor, double-click the name of the A-Table to open and edit it.

Copy and Paste Allocation Table Entries

You can use the Microsoft Windows clipboard to copy and paste an allocation table into a D-Link. You can copy as many allocation table entries as you want, from another D-Link or another Windows application. To paste from the clipboard, the required number of rows must already exist

248 Analyst

Chapter 9: D-Links in the allocation table. You cannot paste the contents of the clipboard if it contains more rows than the selected paste area. If both the source and target for an allocation table are D-Lists, all the entries pasted must be valid entries in both D-Lists. If they are not, they are rejected. If only the target for an allocation table is a D-List, all the pasted entries must contain valid entries in the target; the source entries may contain anything at all.

D-Cube Allocations
A D-Cube allocation uses a slice of a D-Cube consisting of the rows dimension and one D-list formatted column on a single page to act as an allocation table within a D-Link. A D-Cube allocation D-Link is created and run in the same way as a normal D-Link except that a D-Cube is used for data allocation when pairing source and target dimensions. You can run D-Cube allocations inversely and drill down on data transferred by them in the usual way.

Example
If you have a D-Cube that has a D-Cube allocation that allocates cost centers to both divisions and managers as follows:

Divisions
Cost Center 1 Cost Center 2 Cost Center 3 Cost Center 4 Cost Center 5 Cost Center 6 Cost Center 7 Cost Center 8 Cost Center 9 Cost Center 10 Cost Center Total Usa Germany France U.K. USA Germany France U.K. USA Germany

Manager
Manager 2 Manager 3 Manager 1 Manager 1 Manager 2 Manager 4 Manager 4 Manager 1 Manager 3 Manager 3

User Guide 249

Chapter 9: D-Links Cost Center 1 is located in USA and is managed by Manager 2. Similarly, Cost Center 2 is located in Germany and is managed by Manager 3. In this manner, the remaining cost centers are each located in various countries (USA, Germany, England, or France) and managed by various managers (Manager 1 through Manager 4). Note that one manager can be responsible for multiple cost centers in different countries.

Use D-Cube Data in Allocation

If you select Use D-Cube Data from the Allocation Table menu, you select an allocation D-Cube and specify the selection and slice from the allocation D-Cube.

To use D-Cube Allocations

1. Select a D-Cube in the Select D-Cube dialog box. 2. Select an item in the Select dialog box and then click Move >>. 3. Click Slice. 4. Specify the row and column in the Select Row and Column dialog box, and then click OK. 5. Click OK in Select dialog box. 6. Select DList as source or Cube-data as source in the Select Row and Column dialog box, and then click OK.

D-Cube Allocations vs. Lookup and Accumulation D-Links

You can replace any one-dimensional lookup or accumulation D-Link (that is, only one format D-List paired in the D-Link) with a normal D-Link using an allocation table. This becomes a practical option if you use D-Cube allocation tables, but remember that only an accumulation D-Link will perform a break-back allocation when run inversely.

Use Saved Selection in Allocation

As an alternative, from the D-Link menu, you can click Allocation Table, Use Saved Selection to select a predefined selection from the allocation D-Cube.

Select and Slice an Allocation D-Cube

The selection and slice taken from the allocation D-Cube must: have just one page. have just one data column. contain appropriate allocation table entries in the row headings and the data column.

250 Analyst

Chapter 9: D-Links

Enable D-Link to recognize the A-Table

When using a D-Cube as an A-Table in a D-Link, perform the following so the D-Link can recognize the A-Table.

Steps
1. Open the D-Link. 2. Click on the source dimension and click Ctrl + the target dimension. 3. Click Allocate items. 4. From the D-Link menu select Allocation table and Use D-Cube data. 5. Click an allocation D-Cube in the list. 6. Make a selection from the allocation D-Cube, and specify the slice. The selection and slice taken from the allocation D-Cube must: Have just one page Have just one data column Contain appropriate allocation table entries in the row headings and the data column

7. Specify whether the source side of the allocation table is a D-List or a data column.

Complex Allocation D-Cubes

Often allocation D-Cubes are quite simple: They are two-dimensional and contain only two data columns. The simplest possible allocation D-Cube would have just two dimensions and only one data column. In this case, making a selection is unnecessary, but the slice must still be specified correctly. You can create an allocation D-Cube containing any number of dimensions. For example, you can add a versions dimension to an allocation D-Cube if you need to use different versions of four possible allocation tables. If you create a multidimensional allocation D-Cube, you should only include one D-List containing D-List formatted items. If you use a more complex allocation D-Cube in a D-Link you must keep in mind the rules given in the Selecting and Slicing an Allocation D-Cube section when cutting down the selection and taking a slice (the D-Link must have one data column and one page). If you specify a selection and slice that a D-Link cannot interpret as an allocation table, you will see the "Nothing to Transfer" message when the D-Link is run. You will have to return to the D-Link and specify the selection and slice from the allocation D-Cube again. If the D-Link can interpret your selection and slice as an allocation table, but the allocation table does not match the source and/or target items, you will see a 'No items match' message.

A Default Slice in a D-Cube Allocation D-Link

When you use a D-Cube selection as an allocation table in a D-Link the default slice is defined like this: If there is a timescale D-List in the D-Cube, the timescale D-List will form the columns and User Guide 251

Chapter 9: D-Links the first D-List included in the D-Cube will form the rows. If there is no timescale D-List in the D-Cube, the first D-List included in the D-Cube will form the rows and the second D-List included in the D-Cube will form the columns. If you are not sure of the order of D-Lists in a D-Cube, they can be reordered by opening the D-Cube, clicking the D-Cube menu, pointing to Dimensions, and then clicking Reorder. You can eliminate the need to re-slice an allocation D-Cube by including the D-Lists in the following order when you create the D-Cube.

Steps
1. The D-List that you will use most frequently as the source (or the target) in allocation tables. Usually, this is the D-List at the lowest level of the hierarchy. 2. The D-List containing the D-List formatted items. 3. Any other D-Lists.

Editing a D-Cube Allocation D-Link

When you use a D-Cube selection as an allocation table in a D-Link, you have the option when editing the D-Cube allocation either to view the slice which has already been defined and then edit it, or to choose a new cube completely and define a new slice.

Step
With the D-Link open, click on the pairing you wish to edit.

From the D-Link menu click Allocation Table and Use D-Cube Data. The question Do you wish to edit the existing selection? appears. To view and edit the existing selection click Yes. To choose a new cube click No and select a new cube.

Execution Modes
The execution mode determines how data transferred by a D-Link is combined with existing data within a target area (p. 253) of a target D-Cube. There are four D-Link execution modes: Fill (p. 253), Substitute (p. 253), Add (p. 253), and Subtract (p. 253). To set the execution mode, select a setting from the Mode list. The Fill and Substitute modes have a special meaning when applied to Lookup (p. 266) and Accumulation D-Links (p. 272).

Run D-Links inversely

If you run a D-Link inversely (p. 227), the execution mode still applies. The definition of the target area, and the behavior of each of the modes is the same as when a D-Link is run normally, except that the source for the normal D-Link becomes the target for the inverse D-Link (and vice-versa).

252 Analyst

Chapter 9: D-Links Note: You cannot inversely run a D-Link that has an external source because a D-Link cannot target an external source (which also means that the source for an inverse D-Link will always be a D-Cube).

Fill Mode
Fill is the default execution mode. All numbers within the target area (p. 253) of the D-Cube are replaced with the transferred numbers. For a D-Link that uses a D-Cube as its source, Fill and Substitute are identical in behavior for regular D-Links because the target area of the target cube consists only of cells for which data can be found in the source cube. If a D-Link is from an external source or is a look-up or accumulation D-Link then fill mode will set untargeted cells to zero whereas substitute will leave them untouched. In Analyst, for look up and accumulation D-Links (p. 262) any cell within the target area of the cube is set to zero if no data exists in the source cube for that cell. The fill is applied first to zero the data, and then the data is written as if in substitute mode. In Contributor, for a look up and accumulation links that targets both detail and calculated items at the same time, the zeros to fill and the data to set are merged into a single update of the target cube. The different methods for Fill for Analyst and Contributor causes different breakback behavior to occur. If the Analyst method is required for Contributor, you can use one link to zero the data, then an accumulation link running in substitution mode. For a D-Link using an external source, any cell within the target area of the cube is set to zero if no data exists in the source file for that cell.

Substitute Mode
Numbers within the target area of the D-Cube are replaced by the transferred data, but if no data is found in the source for a particular cell, the data in that cell is left unchanged. For look up and accumulation D-Links any cell within the target area of the cube is left untouched if no data exists in the source cube for that cell. For a D-Link using an external source, any cell within the target area of the cube is left untouched if no data exists in the source file for that cell.

Add Mode
Transferred data is added to existing data within the target area of the D-Cube.

Subtract Mode
Transferred data is subtracted from existing data within the target area of the D-Cube.

The Target Area

The target area is the maximum portion of a D-Cube that can be affected by a particular D-Link.

User Guide 253

Chapter 9: D-Links The target area can be described as a selection of items from each of the D-Lists making up the D-Cube, like any other D-Cube selection. The treatment of each target D-List in a D-Link determines which items are within the target area selection.

Type of Target D-List

Unpaired

Target Area Selection

The items selected In an empty selection: all detail items

Allocation table pairing Match descriptions pairing

Items with an entry in the target side of the allocation table With a D-Cube as source: Matched detail items. With an external source: All detail items, except on the DATA dimension where only items matched in the source are selected.

Notice that the type of source completely changes the target selection for a match descriptions pairing. This means that when importing data from an external source, all unmatched target items in a match descriptions pairing are set to zero if the execution mode is set to Fill (p. 253). If a D-Cube is open, a D-Link targeting the D-Cube can only change data within the open selection. Thus, you can run D-Links into limited selections of D-Cubes if you reduce the target area of the D-Link.

Dump Options
The dump option determines the treatment of all unassigned records found in an external source. It is not applicable to D-Links that use a D-Cube as their source. There are four D-Link dump options: Ignore, Edit, Print, and File. The default setting is Ignore, where unassigned records are simply overlooked (any dump item set in an allocation table or match descriptions pairing is still operative). The other three settings will produce a report listing all unassigned records.

To set or change the dump option

1. Create or open a D-Link. 2. Match source and target items. 3. Select a setting from the Dump drop-down box. For allocation table and match descriptions pairings, you can set a dump item in the target D-List. The dump item and the D-Link dump options are not independent - data assigned to a dump item is excluded from the unassigned records report.

254 Analyst

Chapter 9: D-Links

When will records be unassigned?

Items in an external source may be unassigned by the D-Link for the three reasons that follow: For an unpaired source dimension: The items are not to be included in the selected items list. For a match descriptions pairing: The items are not matched (not selected in the source items list). For an allocation table pairing: The items do not have an entry in the source side of the allocation table. Note 1: In the case of the DATA dimension, the source items in the map are cut down so that only those matched with target items by the link are considered to be part of the source, so the unmatched items from the DATA dimension are not considered unassigned and will not be recorded by the Dump Option. Note 2: Records containing bad data will be imported. Any entry in a data column that cannot be interpreted as a number is assumed to be zero and is imported as such. Bad data will not be included in any unassigned records report (unless the record is bad for some other reason). If you drill down on a cell to which bad (zero) data has been assigned, you will see the bad data in the drill down report.

Edit
Unassigned records are presented in a dialog box within Analyst. The field (or fields) within each record that could not be assigned are highlighted in red, enabling you to identify the errors in the source file. You can copy a selection from this report, or you can copy the entire report to the Windows clipboard if required.

Print
Unassigned records are sent directly to the default printer.

File
Unassigned records are written to a delimited ASCII file of your choice.

Steps
1. Open or create a D-Link. 2. Match source items with target items. 3. Select File from the Dump drop-down box. 4. In the Select Dump file dialog box, select a destination directory and a name for the file. 5. Click OK.

User Guide 255

Chapter 9: D-Links The chosen directory and filename are then shown at the top of the D-Link dialog box, along with a button marked with an ellipsis (. . .). Click this button to change the dump file location and/or name.

Dump Item
This option allows you to assign data from all source items in a D-Link that do not have an entry in an allocation table to a single dump item in a target D-List. When the D-Link has run, you can drill down on any data assigned to the dump item to see which records were not matched. If necessary, you can edit the source data file or the local allocation table. You may also need to add an item to the target D-List. The dump item is only applicable when data is being imported from an external source, either a mapped ASCII file, an ODBC database, or Contributor data. If the source for a D-Link is a D-Cube, the dump item is inactive; source items excluded from the allocation table will not be transferred to the target.

To set a dump item within a D-Link

Select an item from the target D-List from the Dump Item box. Do not select a formula item from the target D-List as the dump item. Unmatched records will not be assigned to any formula item.

To discontinue using a dump item

Select None from the Dump Item box. The dump item is one of the tools provided in the D-Link for dealing with bad records. The other is the Dump option, which allows you to control how bad records are treated by the D-Link as a whole. They may be ignored, edited in a screen that highlights the problem area, printed, or output to an ASCII file of your choice. Dump items and Dump options are not independent: Any records assigned to a dump item are excluded from the bad records report. Data in an external source will often contain total lines, which can be very useful for reconciliations. For example, you could add an extra CHECK TOTAL item to a target D-List and allocate a grand total found in the source file to it. When the D-Link has run, you can compare the values in CHECK TOTAL to the values in TOTAL (an existing D-List item that calculates a total for the imported data). Frequently an extra D-List item is added to perform this comparison (containing the formula CHECK TOTAL - TOTAL, for example).

256 Analyst

Chapter 9: D-Links

Drill Down on Data Assigned to Dump Items

If you want to know what data has been assigned to various dump items, drill down on the appropriate numbers transferred into the D-Cube.

Step
Select a cell or a range of cells, then click the Drill Down button.

Dump Items Used with Dump Options

Data assigned to a dump item is excluded from the unassigned records report. An unmatched record cannot be caused by a D-List item that is not included in the selection of items from the source dimension. Because it is not included in the selection, it is not imported into the target D-Cube at all and cannot get assigned to a dump item.

Scale and Round Data within a D-Link

A D-Link can scale and/or round numbers when it is run. All numbers transferred by a D-Link will be scaled and/or rounded by the same factor. It is not possible to set scaling (p. 257) or rounding factors (p. 257) that affect only a subset of data transferred by a D-Link. In a saved A-Table, it is possible to change the sign for selected lines (multiply data assigned by selected allocation table entries by -1). Click the button to use the edit signs feature. If you want to scale or round only some of the numbers a D-Link transfers, you will normally have to create a D-Link, or edit the existing D-Link and save a copy. An alternative is to open only the required limited selection of the target D-Cube, temporarily set a scaling or rounding factor for the D-Link, and then run it. Finally, remove the scaling or rounding factor.

Scaling Factors
You can enter as a scaling factor any number you like, positive or negative. When a D-Link is run, all data transferred is divided by this number. If a rounding factor is also set, data is scaled before it is rounded. Note: Scaling factors can also be set in a D-List. For more information about scaling factors within D-lists, see "Set Scaling Factor within a D-List" (p. 113).

Rounding Factors
The available rounding factors range from six decimal places to millions. When the D-Link is run, all data transferred is rounded to the chosen accuracy. For example:

User Guide 257

Chapter 9: D-Links

Rounding Factor
6 decimals 4 decimals 1 decimal Units Tens Millions

Normal Number
1.123456789 1.123456789 1.123456789 123456789.1 123456789.1 123456789.1

Rounded Number
1.123457 1.1235 1.1 123456789 123456790 123000000

Data midway between two rounded numbers is rounded up. For example:

Rounding Factor
Units Units Tens Tens Millions Millions

Normal Number
0.5 0.499 -5 -5.01 1500000 1499999

Rounded Number
1 0 0 -10 2000000 1000000

If a scaling factor is also set, data is scaled before it is rounded.

Set Scaling and Rounding

Steps
1. Open the appropriate D-Link. 2. From the D-Link menu, click Options. 3. In the D-Link Options dialog box: Select the Use Scaling check box. Type a number (positive or negative) in the Scaling Factor box. Select the Use Rounding check box.

258 Analyst

Chapter 9: D-Links Select a setting from the Rounding Factor list.

4. Click OK. When you next run the D-Link the scaling and rounding options you have set will be active. Remember to save the D-Link if you want to make the change permanent.

Subcolumns
By default, Match Descriptions (p. 233) analyzes the entire text of the dimension item names. However, it is possible to match descriptions on a limited portion of the item names by cutting a subcolumn (p. 259). This is particularly useful when you wish to match items or exclude invalid descriptions. When a subcolumn is cut, the D-Link dialog box displays the cut-down item names. Only entries that are unique within the subcolumn are listed. Often subcolumns are cut when dimension item names contain a unique code and a description (for example, a product code and description). When importing D-List items into a D-List on a regular basis, it is often useful to define which part of a D-List item contains a unique code. This lets you test whether it is a genuinely new item or just a slightly different spelling of the description. The unique portion of the D-List item is case sensitive and takes into account leading and trailing spaces. After you have set the unique part of a D-List item you can not type, paste, or import any duplicate items using a D-Link beginning with that code. For example, a typical product code consists of a code followed by a description such as P03 Camping Gear (P03 is the code, Camping Gear is the description). If, the following month, you are updating the list of product codes and an item named P03 Campin' Gear displays, the program recognizes the code (P03) and ignores the different spelling of the description (Campin' Gear). This prevents duplication of the same product. Remember, if you need to cut subcolumns from the dimensions of a Mapped ASCII file, you can do it in the D-Link as described in the Cut a Subcolumn examples, or you can do it in an ASCII file Map. Note: When working with virtual dimensions, it is impossible to cut a subcolumn.

Cut a Subcolumn
You can cut a subcolumn from any dimension in a D-Link except an unpaired dimension (p. 229) where a selection (p. 232) of items has already been made. However, it is recommended that you pair the dimensions before cutting subcolumns. For a match descriptions pairing (p. 233), this enables you to see which items match as you cut the subcolumns.

User Guide 259

Chapter 9: D-Links If you change the pairing mode (Match Descriptions or Allocate items), or break the connection between paired dimensions, any cut subcolumns are preserved. Even if you change the target for a D-Link, subcolumns cut from source dimensions will be preserved (and vice versa).

Steps
1. From the File menu, click New, D-Link. 2. Click Source and select a source. 3. Click Target and select a target D-Cube. 4. Click a source dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box. 5. Ctrl+click the target dimension that you want to pair with the selected source dimension. Both the source and target dimension names are now selected, and the items of both dimensions are displayed in the D-Link dialog box. 6. Click Match Descriptions. 7. Click the Cut Sub-Column icon. In the Sub-Column dialog box, click at the start of the subcolumn (to the left of the first character of the subcolumn). Note: If the subcolumn starts at the beginning of the item name (at character 1), you do not need to define the start of the subcolumn; you can skip to step 9. The dimension items are displayed in a non-proportional font (each character is the same width) . A ruler at the top of the screen indicates the character number at the end of a column of characters. Left-click - to create a column break Click+drag - to move a column break Right-click - to delete a column break

8. Click at the end of the subcolumn (to the right of the last character of the subcolumn). 9. Click OK. You will return to the D-Link dialog box. The character range in square brackets after the dimension name indicates that a subcolumn has been cut, and displays which characters are included in the subcolumn.

Change the Position of an Existing Subcolumn

Steps
1. Open the relevant D-Link.

260 Analyst

Chapter 9: D-Links 2. Select the required pairing. 3. Double-click the name of the dimension that has the subcolumn you want to change. 4. In the Subcolumn dialog box, drag the column break you want to move. If the existing subcolumn starts at the beginning of the item name and you want the new subcolumn to start at another character, click the point at which you want the subcolumn to start. 5. Click OK. You will return to the D-Link dialog box. The character range in square brackets after the dimension name indicates which characters are included in the new subcolumn.

Clear a Subcolumn
Steps
1. Open the relevant D-Link. 2. Select the required pairing. 3. Double-click the name of the dimension that has the subcolumn you want to change. 4. In the Subcolumn dialog box, right-click the column breaks that you want to remove. If the existing subcolumn starts at the beginning of the item name, you will only need to right-click the end of subcolumn break. 5. Click OK. You will return to the D-Link dialog box. The absence of a character range in square brackets after the dimension name indicates that the subcolumn has been removed.

Duplicate Target Items

When you cut a subcolumn from a target D-List, it is important that the D-List contains unique codes within the subcolumn. Items with duplicated codes are removed from the item listing, and Match Descriptions (p. 233) will only assign data to the first instance of the matching item. For example, consider a target D-List containing the following three items: A001 Description 1 A001 Description 2 A002 Description 3 If the first four characters from this D-List are cut as a subcolumn, the D-Link will display only two items: A001 A002

User Guide 261

Chapter 9: D-Links If A001 is highlighted by match descriptions and the D-Link is run, data will only be assigned to the item A001 Description 1. You may find that duplicate formula items are removed from the list when a subcolumn is cut. This does not matter, as match descriptions does not target formula items unless otherwise specified by clicking Match Calculated Target Items. For example, many D-Lists have a structure like the following: A001 Xx Xxxx A002 Xxxx Xxx Total Group A B001 Xxxx Xx B002 Xxx Xxxxx Total Group B If the first four characters from this D-List are cut as a subcolumn, the D-Link will display only one instance of "Total."

Lookup and Accumulation D-Links

Database D-Cube
A database D-Cube differs from an ordinary D-Cube in that it contains numeric data and text data, which classifies the numeric data. To enable cells to contain text data, The D-List items must be D-List formatted. A D-List format lets you enter text from another D-List in a row or a column.

Terminology
An item in a D-List that has been given a D-List format is called a D-List formatted item. A D-List containing a D-List formatted item is referred to as a lookup D-List. The D-List chosen for the format is called the format D-List.

Sparse D-Cube
A sparse D-Cube contains limited dimensions and sparse data. For example, employee cost data can be held in an ordinary three-dimensional D-Cube, containing the D-Lists Employees, Levels, and Divisions. The following table shows one page of this cube for Employee A.

Division 1
Level 1 0

Division 2
0

Division 3
0

Total
0

262 Analyst

Chapter 9: D-Links

Division 1
Level 2 Level 3 Level 4 0 0 0

Division 2
0 80,000 0

Division 3
0

Total
0 80,000

A sparse D-Cube stores the salary data inefficiently. Each page of this D-Cube contains just one number; thus, this D-Cube is a sparse D-Cube. However, you can transfer data from this D-Cube into a D-Cube containing a Divisions D-List using a normal D-Link. Alternatively, the data in the D-Cube above can be held in a simpler two-dimensional D-Cube.

Employees
A B C D E

Salary
80,000 50,000 45,000 60,000 20,000

This is also a sparse D-Cube, and there are two problems with it: First, you can no longer see which level or division an employee belongs to. Secondly, it is awkward to create a normal D-Link to transfer this data into another D-Cube that contains a Divisions D-List. You have to create an allocation table to assign each employee separately. You can store this allocation of Employees to Divisions in a saved A-Table and use this in D-Links. Alternatively, you can create a special allocation D-Cube, and use the Allocate Using D-Cube Data option when you create the D-Link. For more information see "Use D-Cube Data in Allocation " (p. 250). The latter approach is preferable because an allocation D-Cube is easier to maintain and update than a saved A-Table. However it would be more efficient to store the data in a two dimensional cube as follows. Here the D-List forming the columns would have two D-List formatted items, Division, formatted on a Divisions D-List and Level formatted on a Levels D-List. Only the Salary item would be numeric.

Employees
A B

Division
Division 3 Division 2

Level
Level 2 Level 4

Salary
80,000 50,000

User Guide 263

Chapter 9: D-Links

Employees
C D E

Division
Division 1 Division 4 Division 2

Level
Level 5 Level 3 Level 6

Salary
45,000 60,000 20,000

Lookup and Accumulation D-Link Restrictions

There are certain restrictions imposed when creating lookup or accumulation D-Links. You cannot create a simultaneous lookup and accumulation D-Link. If both the source and target D-Cubes contain D-Lists with D-List formatted items, the D-Link will display format D-Lists in both the source and target D-Cubes. However, after you have paired a format D-List in the source, you cannot pair a format D-List in the target.

You cannot use multiple lookup D-Lists. If a D-Cube contains multiple D-Lists each with D-List formatted items, the D-Link will display the format D-Lists belonging to more than one lookup D-List. After you have paired a format D-List belonging to one lookup D-List, you cannot pair other format D-Lists that belong to a different lookup D-List. You may, however pair multiple format D-Lists if they all belong to the same lookup D-List. You can only create lookup and accumulation D-Links when the source for the D-Link is a D-Cube or Contributor cube. You cannot use the scaling or rounding options (p. 257) in a lookup or accumulation D-Link. You cannot use a saved A-Table that uses the sign changing option in a lookup or accumulation D-Link. You cannot cut subcolumns (p. 259) from a format D-List. You cannot make many to one allocations on the real dimensions of a lookup D-Link

Lookup D-Links
Lookup D-Links are D-Links that literally "look up" data from a source D-Cube based on text data using a database D-Cube as a target. You define a D-Link as a lookup D-Link by selecting the Link Type, pairing a normal D-List from a source D-Cube with a format D-List from a target D-Cube. Normally source and target D-Lists are formatted to use the same D-List. For example create a two dimensional cube containing Salaries based on levels.

264 Analyst

Chapter 9: D-Links

Level
Level 1 Level 2 Level 3 Level 4 Level 5

Salary
60,000 70,000 80,000 85,000 100,000

Use this as a source D-Cube and set up a D-Link to transfer the salary to a Costs D-Cube based on Level. When this D-Link is run, data is transferred to the employees in the Employee Costs D-Cube based on level:

Employees
A B C D E

Division
Division 1 Division 1 Division 2 Division 3 Division 2

Level
Level 3 Level 2 Level 5 Level 1 Level 1

Salary
80,000 70,000 100,000 60,000 60,000

In this example, the Employee Costs D-Cube is the database D-Cube, and the Annual Salaries D-Cube is the source D-Cube. The paired format D-List (Levels) drives the lookup D-Link when it runs.

One-dimensional Lookup D-Links

A one-dimensional lookup D-Link is based on two criteria: It must contain at least one D-List formatted item that can be used as a target. Only one format D-List is paired in the D-Link.

Two-dimensional Lookup D-Links

A two-dimensional lookup D-Link is based on two criteria. It must contain at least two D-List formatted items that can be used as targets.

User Guide 265

Chapter 9: D-Links Two format D-Lists are paired in the D-Link.

Create a Two-dimensional Lookup D-Link

Creating a two-dimensional lookup D-Link is the same as creating a one-dimensional lookup D-Link, except that instead of pairing only one virtual dimension, you pair two virtual dimensions.

Lookup D-Link Execution Modes

The Fill and Substitute execution modes (p. 253), set using the Mode drop-down box in a lookup D-Link, have a special function when applied to lookup and accumulation D-Links. If a dimension formatted on a D-List contains an entry that is not matched by a D-Link, the corresponding data will be set to zero if the mode is set to Fill, and left untouched if the mode is set to Substitute.

Unpaired Dimensions in Lookup D-Links

If you leave a lookup D-List unpaired, you should never leave it with an empty selection. Nor should you select the D-List formatted item that is used to drive the D-Link from the lookup D-List.

Steps
1. Click an unpaired dimension. The items of the selected dimension are displayed in the dimension items section of the D-Link dialog box, ready for you to make a selection of items. 2. Click Select to make a selection of items. 3. Double-click an item in the dimension items list to move it to the Selected items box. To select more than one item, highlight the required items in the dimension items list, then click the arrow button pointing in the direction of the selected items list. Repeat steps 1 through 3 for all remaining unpaired source and target dimensions.

Run Lookup D-Links Inversely

You can run lookup D-Links inversely the same as normal D-Links.

Steps
1. Open the target D-Cube - the target database for the normal D-Link, which will be the source when the D-Link is run inversely. 2. Click the Run D-Link button. 3. Select a D-Link from the list of those targeting the D-Cube and click Inverse. A lookup D-Link run inversely does not become an accumulation D-Link. For example, the source D-Cube (Salary by Level) for a lookup D-Link contains the D-Lists, Levels and Salaries, and the following data.

266 Analyst

Chapter 9: D-Links

Salary by Level D-Cube Level

Level 1 Level 2 Level 3 Level 4 Level 5

Salary
60,000 70,000 80,000 85,000 100,000

The target D-Cube (Employee Costs) for the lookup D-Link contains the D-Lists, Employees and Employee Attributes. Employee Attributes contains two D-List formatted items Division and Levels. It contains the following data.

Employee Attributes D-Cube Employees

A B C D E

Division
Division 1 Division 1 Division 2 Division 3 Division 2

Level
Level 3 Level 2 Level 5 Level 1 Level 1

Salary
80,000 70,000 100,000 60,000 60,000

In the lookup D-Link to transfer data from Salary by Level to Employee Costs, the item Salary within the target D-List Employee Attributes, is paired with the item Salary in the source. The target D-List Employees is left with an empty selection (p. 232) (auto-allocated D-Lists). The source D-List Levels, is paired with the target format D-List Levels using match descriptions. In a lookup D-Link, unpaired D-Lists in the target D-Cube that do not contain a selection are referred to as auto-allocated D-Lists (with the exception of the lookup D-List). Each (detail) item in an auto-allocated D-List contains one entry from the driving format D-List (that is, in the driving D-List formatted item in the lookup D-List). This entry determines which data is taken from the driving source D-List. If this lookup D-Link is run inversely with the execution mode set to Substitute, the data in Salary by Level is unchanged.

User Guide 267

Chapter 9: D-Links However, if it is run with the mode set to Fill, the data in Salary by Level will be changed as follows because there is no data in the Employee Attributes cube for level 4 - so this is set to zero.

Level
Level 1 Level 2 Level 3 Level 4 Level 5

Salary
60,000 70,000 80,000 0 100,000

If Employee Costs contains inconsistent data, the last matching entry (based on D-list order) from this database D-Cube is transferred. For example, if Employee Costs contains the following data:

Employees
A B C D E

Division
Division 1 Division 1 Division 2 Division 3 Division 2

Level
Level 3 Level 2 Level 5 Level 1 Level 1

Salary
80,000 70,000 100,000 60,000 45,000

and the lookup D-Link is run inversely, then the following data is transferred to the Salary by Level D-Cube:

Execution Mode Set to Substitute Level

Level 1 Level 2 Level 3 Level 4

Salary
45,000 70,000 80,000 85,000

268 Analyst

Chapter 9: D-Links

Level
Level 5

Salary
100,000

Execution Mode Set to Fill Level

Level 1 Level 2 Level 3 Level 4 Level 5

Salary
45,000 70,000 80,000 0 100,000

These same results would be obtained even if the D-Cube were re-sorted in any way based on the cube data, as the last matching item is based on the order of the Employees D-List.

D-Lists Used in Lookup D-Links

In a normal D-Link, all D-Lists are equivalent: Format D-Lists (p. 109). Virtual dimensions may appear, but as long as they are not paired, they will play no part in the D-Link. In lookup D-Links, however, the treatment of D-Lists depends on which format D-Lists have been paired. D-Lists are treated like this:

Normal D-Lists paired with Format D-Lists

These pairings drive the lookup D-Link. The normal D-List in the source that is paired with a format D-List in the target is referred to as the driving source D-List; the format D-List in the target is referred to as the driving format D-List. Data is taken from the driving source D-List and allocated to target auto-allocated D-Lists (see below for a description of auto-allocated D-Lists) according to the contents of the driving D-List formatted item in the target lookup D-List.

Unpaired Format D-Lists

Unpaired format D-Lists have no effect in a lookup D-Link. If you do not pair any target format D-Lists, you will create a normal D-Link.

Normal D-Lists Paired with Normal D-Lists

These pairings are treated the same way as a normal D-Link.

User Guide 269

Chapter 9: D-Links

The Target Lookup D-List

The target lookup D-List contains the D-List formatted items used to drive the D-Link. This D-List is treated the same way as a normal D-Link, except that you should not leave it unpaired with an empty selection or target the driving D-List formatted items. If you do target the driving D-List formatted items, the data transferred by the D-Link will destroy the data used to drive the D-Link. You must identify the item or items in a target lookup D-List, which use the data transferred by the D-Link. Data is not allocated automatically into this D-List. You can use only one lookup D-List in a lookup D-Link. For information about restrictions, see "Lookup and Accumulation D-Link Restrictions" (p. 264).

Unpaired D-Lists in the Target

These are referred to as the auto-allocated D-Lists, with the exception of a lookup D-List. Each detail item in an auto-allocated D-List will contain one entry from the driving format D-List (the driving D-List formatted item in the lookup D-List). This entry determines which data is taken from the driving source D-List.

Unpaired D-Lists in the Source

These D-Lists are treated the same way as a normal D-Link.

Accumulation D-Links
Accumulation D-Links are D-Links that consolidate data from a source database D-Cube to a target sparse D-Cube (p. 262) based on D-List formatted text. You can run an accumulation D-Link inversely to perform a breakback (p. 149) allocation in the database D-Cube. You define a D-Link as an accumulation D-Link by pairing a format D-List in a source D-Cube with a normal D-List in a target sparse D-Cube and selecting Accumulation as the D-Link type. Normally source and target D-Lists are formatted to use the same D-List. You need to specify the D-Link as an accumulation D-Link based on how the dimensions of the source and target correspond by pairing a formatted D-List with a normal target D-List dimension. You can create an accumulation D-Link in more than one dimension by pairing more than one source format D-List. Be cautious because certain restrictions (p. 264) apply.

D-Lists Used in Accumulation D-Links

In a normal D-Link, all D-Lists are equivalent. Format D-Lists (virtual dimensions) may appear, but as long as they are not paired, they will play no part in the D-Link. In accumulation D-Links, however, the treatment of D-Lists depends on which format D-Lists have been paired. In an accumulation D-Link (that is, a format D-List in the source paired with a normal D-List in the target), D-Lists are treated like this:

270 Analyst

Chapter 9: D-Links

Format D-Lists paired with normal D-Lists

These pairings drive the accumulation D-Link. The format D-List in the source is referred to as the driving format D-List, and the normal D-List in the target is the driving target D-List. Data in the source auto-consolidated D-Lists is consolidated into a driving target D-List according to the contents of the driving D-List formatted item in the source lookup D-List. In an accumulation D-Link, unpaired D-Lists in the source D-Cube that do not contain a selection are referred to as auto-consolidated D-Lists (with the exception of the lookup D-List). Each (detail) item in an auto-consolidated D-Lists will contain one entry from the driving format D-List (that is, in the driving D-List formatted item in the lookup D-List). This entry determines which item in the driving target D-List will take data.

Unpaired Format D-Lists

Unpaired format D-Lists play no part in the D-Link. If you do not pair source format D-Lists, you will create a normal D-Link rather than an accumulation D-Link.

Normal D-Lists paired with normal D-Lists

These pairings are treated in the same way as for a normal D-Link.

The source Lookup D-List

The lookup D-List contains the D-List formatted items used to drive the D-Link, and is treated in the same way as a normal D-Link, except that you should not leave it unpaired with an empty selection; otherwise it will take data from the driving D-List formatted items. If you do, you will include the D-List formatted data in the data transferred by the D-Link. You must identify the item, or items in this D-List containing the data you want the D-Link to transfer. Data is not consolidated automatically from this D-List. There can only be one lookup D-List in an accumulation D-Link. For information about restrictions, see "Lookup and Accumulation D-Link Restrictions" (p. 264).

Unpaired D-Lists in the source

These are referred to as the auto-accumulated D-Lists with the exception of the lookup D-List. Each detail item in an auto-accumulated D-Lists will contain one entry from the driving format D-List (the driving D-List formatted item in the lookup D-List). This entry determines which item in the driving target D-List will take data.

Unpaired D-Lists in the target

These D-Lists are treated the same way as for a normal D-Link.

One-dimensional Accumulation D-Links

A one-dimensional accumulation D-Link is based on two criteria.

User Guide 271

Chapter 9: D-Links It must contain at least one D-List formatted item (p. 117) that can be used as a source to consolidate data from a database D-Cube to a target D-Cube based on text data. Only one format D-List is paired in the D-Link.

Two-dimensional Accumulation D-Links

A two-dimensional accumulation D-Link is based on two criteria. It must contain at least two D-List formatted items (p. 117) that can be used as sources to consolidate data from a database D-Cube to a target D-Cube based on text data. Two format D-Lists are paired in the D-Link.

You define a D-Link as a two-dimensional accumulation D-Link by pairing two format D-Lists in a source D-Cube with two normal D-Lists in a target D-Cube. Normally source and target D-Lists are formatted to use the same D-Lists.

Create a Two-dimensional Accumulation D-Link

Creating a two-dimensional accumulation D-Link is the same as creating a one-dimensional accumulation D-Link, except that instead of pairing only one virtual dimension, you pair two virtual dimensions.

Accumulation D-Link Execution Modes

The Fill and Substitute execution modes (p. 253) (set using the Mode drop-down box in an accumulation D-Link) have a special function when applied to lookup and accumulation D-Links. If the mode is set to Fill, all data in the target D-Cube is replaced and data that is not represented in the database D-Cube is set to zero. When the mode is set to Substitute, data that is not represented in the database D-Cube is left untouched. For example, the source D-Cube (Employee Costs) used for an accumulation D-Link contains the D-Lists, Employees and Employee Attributes. The D-List Employee Attributes contains two D-List formatted items Division and Levels. It contains the following data:

Employees
Employee A Employee B Employee C Employee D Employee E

Division
Division 1 Division 1 Division 2 Division 3 Division 2

Level
Level 3 Level 2 Level 5 Level 1 Level 1

Salary
80,000 70,000 100,000 60,000 45,000

The target D-Cube (Levels by Divisions) for the accumulation D-Link contains the D-Lists, Divisions and Levels. Initially, it contains the following data: 272 Analyst

Chapter 9: D-Links

Division 1
Level 1 Level 2 Level 3 Level 4 Level 5 1,000 1,000 1,000 1,000 1,000

Division 2
1,000 1,000 1,000 1,000 1,000

Division 3
1,000 1,000 1,000 1,000 1,000

Division 4
1,000 1,000 1,000 1,000 1,000

Division 5
1,000 1,000 1,000 1,000 1,000

Total
5,000 5,000 5,000 5,000 5,000

In the accumulation D-Link to transfer data from Employee Costs to Levels by Divisions, the source D-List, Employee Attributes, is left unpaired with the item Salary, selected. The source D-List, Employees, has been left an empty selection (auto-allocated D-Lists). The source format D-List, Divisions, is paired with the target D-List, Divisions, using match descriptions (p. 233). The source format D-List, Levels, is paired with the target D-List, Levels, using match descriptions. If the execution mode for the D-Link is set to Fill, the following data is transferred to the Levels by Divisions cube:

Division 1
Level 1 Level 2 Level 3 Level 4 Level 5 0 70,000 80,000 0 0

Division 2
45,000 0 0 0 100,000

Division 3
60,000 0 0 0 0

Division 4
0 0 0 0 0

Division 5
0 0 0 0 0

Total
105,000 70,000 80,000 0 100,000

Some of the cells are set to zero because no record was found in the database D-Cube. If the execution mode for the D-Link is set to Substitute, the following data is transferred to the Levels by Divisions cube:

Division 1
Level 1 Level 2 Level 3 1,000 70,000 80,000

Division 2
45,000 1,000 1,000

Division 3
60,000 1,000 1,000

Division 4
1,000 1,000 1,000

Division 5
1,000 1,000 1,000

Total
108,000 74,000 84,000

User Guide 273

Chapter 9: D-Links

Division 1
Level 4 Level 5 1,000 1,000

Division 2
1,000 100,000

Division 3
1,000 1,000

Division 4
1,000 1,000

Division 5
1,000 1,000

Total
5,000 104,000

The cells without records stay the same (the data is still 1,000).

Run Accumulation D-Links Inversely

You can run accumulation D-Links inversely the same as normal D-Links. For more information, see "Tun an Inverse D-Link" (p. 227). An accumulation D-Link run inversely does not become a Lookup D-Link. Instead, it performs a break back allocation over the source data. For example, the source D-Cube (Employee Costs 2) for the accumulation D-Link contains the D-Lists, Employees and Employee Attributes. The Employee Details D-List contains the D-List formatted items, Divisions and Levels, formatted on the D-Lists, Divisions and Levels, respectively. Initially, it contains the following data.

Division
Employee A Employee B Employee C Employee D Employee E Division 1 Division 1 Division 2 Division 3 Division 5

Levels
Level 3 Level 2 Level 5 Level 1 Level 1

Basic Salary Benefits

80,000 70,000 100,000 60,000 60,000 8,000 8,000 4,000 4,000 4,000

Total Salary
88,000 78,000 104,000 64,000 64,000

The target D-Cube (Overheads) for the accumulation D-Link contains the D-Lists, Levels and Divisions. It contains the following data.

Division 1

Division 2

Division 3

Division 4

Division 5

Divisional Total
658,000 24,000 0

Basic Salary Benefits Other Overheads

223,000 8,000 0

112,000 4,000 0

193,000 4,000 0

55,000 4,000 0

75,000 4,000 0

274 Analyst

Chapter 9: D-Links

Division 1

Division 2

Division 3

Division 4

Division 5

Divisional Total
682,000

Total Overheads

231,000

116,000

197,000

59,000

79,000

In the accumulation D-Link to transfer data from Employee Costs 2 to Overheads, the source D-List, Employee Attributes 2, is paired with the target D-List Overheads and the items, Basic Salary and Benefits, are matched. The source D-Lists, Employees and Levels, has been left with an empty selection (p. 232) (an auto-accumulated D-List). The source format D-List Divisions is paired with the target D-List Divisions using match descriptions (p. 233). In a lookup D-Link, unpaired D-Lists in the target D-Cube that do not contain a selection are referred to as auto-allocated D-Lists (with the exception of the lookup D-List). Each (detail) item in an auto-allocated D-List contains one entry from the driving format D-List (that is, in the driving D-List formatted item in the lookup D-List). This entry determines which data is taken from the driving source D-List. The data in Overheads has been transferred from Employee Costs 2 using the accumulation D-Link described above.

Division 1

Division 2

Division 3

Division 4

Division 5

Divisional Total
370,000 28,000 0

Basic Salary 150,000 Benefits Other Overheads Total Overheads 16,000 0

100,000 4,000 0

60,000 4,000 0

0 0 0

60,000 4,000 0

166,000

104,000

64,000

64,000

398,000

But, suppose we change the number in the Division 2 column, Benefits row from 4,000 to 8,000. And then run the accumulation D-Link inversely. The following data is transferred to Employee Costs 2 D-Cube.

Division
Employee A Employee B Employee C Division 1 Division 1 Division 2

Levels
Level 3 Level 2 Level 5

Basic Salary Benefits

80,000 70,000 100,000 8,000 8,000 8,000

Total Salary
88,000 78,000 108,000

User Guide 275

Chapter 9: D-Links

Division
Employee D Employee E Division 3 Division 5

Levels
Level 1 Level 1

Basic Salary Benefits

60,000 60,000 4,000 4,000

Total Salary
64,000 64,000

Note that Employee C's benefits have increased from 4,000 to 8,000. When an accumulation D-Link is run inversely, any holds set in the source D-Cube are respected. Also, where there are a number of detail items, the total is broken back in the same ratio as the detail items.

Analyst<>Contributor Links
You can transfer data between Contributor and Analyst using Analyst's D-Link function. All the standard features of a normal D-Link are available. For example, the use of A-tables, D-Cube allocations, local allocation tables, match descriptions, and matching on codes. There are three types of links available: Analyst>Contributor Contributor>Analyst Contributor>Contributor

When to use Analyst<>Contributor Links

For small amounts of data, an Analyst<>Contributor link can be a quick and effective method of transferring data. Analyst <> Contributor links use the Analyst link engine, which was designed to efficiently move small amounts of data. If you attempt to move large amounts of data, it can result in performance issues. For large amounts of data, it can be more efficient to import data in and out of Contributor using Contributor's import and publish facilities. This is because Contributor can be scaled out to make use of multiple computers and processors. Analyst<>Contributor links work in the same way as a standard Analyst D-Link. They treat Contributor as a single large cube which means that with large models, you can quickly run into memory problems. Because of these limitations, we recommend that Analyst<>Contributor links should only be used for doing ad-hoc transfers of small amounts of data of no more than 10 - 20 e.List items at a time.

Using the @SliceUpdate Macro

You can avoid memory problems for links that target an entire e.List in Contributor by using the @SliceUpdate macro. This macro processes the link in slices of the e.List, making it a much more scalable solution.

276 Analyst

Chapter 9: D-Links

How Analyst<>Contributor links differ from Standard D-Links

Most D-Links that have Contributor as a source or target behave the same as normal Analyst D-Links. The few exceptions are listed below: Lookup D-Links are not allowed where Contributor is the target. This is because Lookup D-Links depend on the data in the target cube, but in a Web environment, this data can be changing all the time. You are not allowed to target calculated items in Contributor. This includes totals on the e.List dimension as well as any total in other D-Lists. Match descriptions in Analyst D-Links to/from Contributor will treat the pipe symbol as a blank. The pipe symbol is used in Analyst as a line-feed for column headers. It is stripped out when you create a Contributor application from an Analyst model. You cannot target an Assumptions Cube in Contributor, although you can have one as a source. For Analyst>Contributor links, each e.List item of a Contributor cube can only be targeted by a single D-Link for each time you Go to Production. If you inadvertently run two D-Links that target the same e.List item of a Contributor cube, the D-Link you run last will be the one to run, and any earlier D-Links will be ignored. However two different D-Links may target the same cube provided that they target different e.List items. You cannot target No Data cells as defined by access tables in Contributor. However, as the Administrator, you are not subject to the restrictions imposed on Contributor users entering data via the Web client, so hidden and read-only cells are not applicable. You can write to these cells just as you can using normal import routines. Analyst<>Contributor links cannot be run inversely.

Otherwise, most D-Link types will be permitted. You can use Match Descriptions, local allocation tables, A-tables, and D-Cube allocations. You can cut subcolumns, letting you match on codes. You can run accumulation links both ways, but lookup links run from Contributor to Analyst only. Note: If you use a saved allocation table and rename when using Contributor as a source or target in a D-Link, the allocation table must be manually updated in order for the D-Link to work like it did before the item was renamed.

Installation
Analyst users who do not have the Contributor Administration Console installed are not able to run Analyst<>Contributor D-Links. Note: When you have installed Client tools onto a workstation, it is installed only for the user doing the installation.

Security
To run a Contributor<>Analyst link, users must: Have Analyst and the Contributor Administration Console installed.

User Guide 277

Chapter 9: D-Links Belong to a user, group or role which gives them rights to Analyst and the appropriate Contributor applications.

In addition, organizations may lock down access to the database or the Web server using the IP address, limiting who can run these links. Note: D-Links from ASCII and ODBC directly into Contributor are not allowed. You must use Contributor Import to do this.

How Analyst<>Contributor and Contributor<>Contributor Links Work

You set up a Analyst<>Contributor link in the same way as you would a standard D-Link, choosing Contributor as the source or target of a D-Link. All the data is prepared in Analyst. The steps for setting up any Analyst<>Contributor or Contributor<>Contributor link are: In the Analyst D-Link editor, choose Contributor Data as the source or target. Select a Datastore server (if more than one is available). Select a Contributor application. You may need to click the Refresh button to the right of the Name list to get the list of available Contributor applications. Click Test Connection, then click OK. Select whether to target the production system or the development system of the Contributor application. Select a Contributor cube. Pair dimensions against the target (or source) cube as you would for a normal D-Link.

Analyst>Contributor Links
These links can target either the production or development version of Contributor. If targeting the development version, they only appear on the Contributor screens after the Go to Production process is completed. If targeting the production version, you do not need to run a full Go to Production process. Instead, an activate process is run which moves the data into the import production queue and creates a snapshot of the data at the time the link was executed. Then a reconcile job is triggered, which updates the e.List items with the new data. The following steps occur when you target the development application. When you run an Analyst>Contributor Link, the data is read out of Analyst when you run the D-Link. The prepared data is written directly to the import queue in the Contributor application datastore as a prepared data block, e.List item by e.List item when you run the Go to Production process in the Contributor Administration Console, or through Automation.

278 Analyst

Chapter 9: D-Links You can have multiple links target the same e.List in the same Contributor cube. This is done by having each link create its own bucket in the import queue, so multiple links in the same import queue can target the same e.List. If the same link is run twice, the last run will overwrite the first run in the bucket.

There may be a delay between the Go to Production process and the data being reconciled in the Web client. If, in the meantime, a planner has edited one of the cells targeted by the link, that cell will be overwritten when the reconciliation takes place. This behavior is very similar to the reconciliation that takes place when you import data into Contributor from text files or via DTS. The following occurs when targeting the production application: The data is read out of Analyst when you run the D-Link. An activate process is run that applies the data to a cube. If running the link through the Analyst interface, the activate process happens automatically. If running the link using macros, you must run the @DLinkActivateQueue macro to activate the link. The import queue targeting the production system can be activated from Analyst.

Recommendation - Use Macros for Multiple Analyst >Contributor Links

If you have multiple Analyst > Contributor links that target the same Contributor application, and that target production, we recommend that you use Analyst macros. This means that you can run multiple links one after the other in the macro that all target the same Contributor application, and then run a single activation step. This is much quicker than running multiple Analyst >Contributor links from the Analyst user interface because after each link, the activate process runs automatically. It is also quicker than running a link that targets development and then running Go to Production.

Contributor>Analyst Links
The following steps occur when a Contributor>Analyst Link is run: A snapshot is taken of the production version of the Contributor Application. To ensure a consistent read if you are using the @SliceUpdate macro, take the Contributor application offline, or use the @DLinkExecuteList macro. The link process causes a prepare publish job to be run. You can monitor this in the Contributor Job Management screen. Once the Prepare publish job has run, a publish job is created and immediately set to ready. Note that the job is not run, this is because the Contributor job executor is not used. Analyst executes the transfer of data. A Contributor session is loaded and the entire data block is loaded for each e.List item. If the link is set up for more than one e.List item, it is the equivalent of loading a multi-e.List item view; a very memory intensive process. The data is written directly to the Analyst cube data file (H2D file).

User Guide 279

Chapter 9: D-Links

Contributor>Contributor Links
These links go from the Production version of a Contributor source into the development version of the Contributor target. They are typically used between separate applications. If the applications are small, Contributor>Contributor links can be fast. However, if you transfer data between larger applications this way, you may run into problems due to memory use and scalability problems. You can avoid these issues by using the @SliceUpdate macro. You can also use Administration Links in the Contributor Administration Console. These copy data between Contributor cubes and applications. This process is scalable and so can move large volumes of data into either the development or production version of the Contributor application.

Copying Analyst<>Contributor Links

There are three methods for making copies of links. Save As, Library Objects, and Library Copy Wizard. These three methods of copying Analyst<>Contributor links affect whether the link refers to the original application or a new application.

Save As Method
This method results in a copy which refers to the original Contributor application(s) and/or Analyst D-Cubes.

Steps
1. Open the link. 2. From the File menu, click Save As. 3. Choose a Library in which to copy the link. 4. Enter a name for the link copy. 5. Click OK.

Library Method
This method lets you select the link with or without other objects and choose either to copy or move the link. This results in a link which refers to the original Contributor application(s) although the source or target Analyst D-Cube (if it is not a Contributor > Contributor link) could be changed by this method if certain reference options are chosen when copying.

Steps
1. From the File menu, click Library, Objects. 2. Select the link with or without other objects and move it down. 3. Click the Copy selected objects button.

280 Analyst

Chapter 9: D-Links 4. In the Copy dialog box, enter a new name for the link, select a target library in which to copy the link, and select how to remap references. 5. Click OK.

Library Copy Wizard Method

This method lets you make a copy of an Analyst<>Contributor link which refers to a new application based on a copied library.

Things to Watch Out For

Using the Library Copy wizard to create duplicate objects within the same library will not work for making copies of links because if you copy template D-Cubes containing the e.List, and include the e.List itself in the selection of objects, the e.List will be copied. Thus when you synchronize Contributor, the new cube you have created will be an assumption cube as it does not contain the original e.List. A link can only be pointed to an application where it will refer to template cubes which were copied at the same time. You cannot copy a link into a library which already contains suitable template cubes and then refer the link to an application based on that library. If you make a copy of a link using this method and copy the link and its associated objects at the same time, then you will not be able to refer the link back to the original application. You will have to make a new application based on the copied library and refer the link to this new application. If you copy macros which refer to Contributor applications using the Library Copy wizard, then the macros will continue to refer to the original application. You must open the copied macros and manually edit them to refer to any new applications based on copied libraries.

Steps
1. Use the Library Copy wizard to copy the link and any related Analyst template cubes at the same time. 2. Create a Contributor application based on the copied Analyst template D-Cubes. 3. Point the link to your new application by using one of two ways. Open the link and then select your new Contributor application when prompted. From the File menu, click Library, Object. Double-click the link to move it down and then right click the link and select Change Contributor source on D-Links.

Factors That Can Affect Memory Usage

Memory limits can be hit, depending on the following: Density of data being transferred by links.

User Guide 281

Chapter 9: D-Links Available RAM. The more available, the better. Multi-e.List item views with access tables, are not cut down as much as a single e.List item view with access tables. Maximum workspace setting (MAXWS) in Analyst.

This is the amount of space reserved for use by Analyst. As a general rule, this should not be more than half the available RAM. Setting this option too high can grab so much memory for the Analyst process that it does not leave enough for the Contributor process.

Opening a Link From a Computer that Does not Have Access to the Original Datastore
If a Contributor cube is used as a source or target, and the link is opened from a computer different from the one the link was created on (different datastore), you are prompted to reselect the connection and application to point to the data store and application name that holds the cube the link was built on. All matching is then preserved. You save the link, and the new connection will be saved, and the link will run in the future. This allows multiple data sources to be used. If the two applications are built from the same Analyst library, the GUIDs will match when pointing the link to the original datastore. Running a link from a workstation that does not have access to the original datastore will require manually opening the link and reselecting the connection. You can also update the connection for several links at once. Note: Analyst <>Contributor and Contributor <>Contributor links are associated with Contributor applications using unique identifiers (GUIDs). If you change the source or target Contributor application, you must remap the D-Link connections because the GUIDs have changed.

Steps
1. Click File, Library, Objects and select the links that you want to update and move then to the bottom pane. 2. In the bottom pane, right click and select Change Contributor Source on D-Links. 3. Enter the connection details for the new datastore. 4. Select the appropriate substitution option. This will update all the selected links with the new connection details.

Running Batches of D-Links using the @DLinkExecuteList macro

@DLinkExecuteList is a macro designed to run a series of D-Links in order. The @DLinkExecuteList macro behaves similarly to a series of @DLinkExecute steps, with a subtle difference when D-Links have Contributor as a source. When the macro runs the first D-Link that has Contributor as a data source, it logs the time and takes a consistent read of the database. All subsequent D-Links that have the same Contributor source use the data from that point in time

282 Analyst

Chapter 9: D-Links rather than the actual time when the D-Link is run. This ensures consistency across D-Links coming from the same Contributor data source. If a subsequent D-Link in the macro has a different Contributor data source, the old source is closed and the new one opened. Similarly, if you have two @DLinkExecuteList steps in the same macro or in a sub-macro called via a @MacroExecute step, each time the old data source is closed and the new one is opened.

Steps to set up @DLinkExecuteList

1. Click Edit Object List in the Macro wizard. 2. Select the D-Links you want to run. You must select only D-Links, because anything other than D-Links are ignored. You may include any set of D-Links, whether they be normal Analyst > Contributor, or Contributor > Analyst D-Links.

Running D-Links While Making Model Changes

If you want to make changes to the Contributor model and import data into Contributor using Analyst>Contributor D-Links, it is important that you synchronize first, then run the D-Link. For example, if you have inserted a new product as part of a model change, you cannot import data into the new product until the Contributor model has been synchronized. You must then run Go to Production so that the model and data changes become live. So, if you make any changes to an Analyst model, then want to populate the Contributor cube, the order is as follows: Synchronize Run the D-Link Run Go to Production.

You can use Contributor>Contributor links to preserve data during cube dimensional restructuring, for example when adding a dimension.

Steps
1. Take the Contributor application offline. 2. Run a link from the production version of the Contributor application to the import queue of the development application. 3. Run Go to Production.

Fill and Substitute Mode

In Contributor<>Analyst D-Links, Fill and Substitute Modes behave in the same way as normal D-Cube to D-Cube D-Links in Analyst. Fill and Substitute modes generally only apply to lookup and accumulation D-Links. In Substitute mode, the data in the untargeted area of the D-Link remains unchanged. In Fill mode, the untargeted cells get set to zero when the D-Link is run. User Guide 283

Chapter 9: D-Links However, this only applies to lookup and accumulation D-Links. In normal D-Links, if an item is not included in the right-hand side of an allocation table, it is assumed to be untargeted, so the original target data is kept unchanged, irrespective of whether you use Fill or Substitute mode. Similarly, on normal real dimension pairings that use match descriptions, unmatched items are kept untouched when the D-Link is run. This applies to both Fill and Substitute modes.

Action Applied to Untargeted Cell D-Cube or Contributor Cube asSource

Fill Allocation Tables lookup Accumulation Keep Zero Zero Substitute Keep Keep Keep Keep

File Map (ODBC or ASCII) as Source

Fill Keep Not Applicable Not Applicable Zero Keep Substitute Keep

Match Descriptions Keep

Effect of Access Tables in Contributor

If Contributor is the source, cells marked as No Data are treated as zero when running a D-Link into an Analyst or Contributor target D-Cube. If Contributor is the target, you cannot target No Data cells as defined by access tables in Contributor. However, as the Administrator, you are not subject to the restrictions imposed on Contributor users entering data via the Web Client, so hidden and read-only cells are not applicable. You can write to these cells just as you can using normal import routines.

Select Contributor Application

When you choose a Contributor cube as either the source or the target of a D-Link, you are prompted to select a Contributor Application.

Steps
1. Select the Datastore provider: SQL Server, Oracle or DB2. 2. Enter the Datastore server name, or click the browse button to navigate to the server (SQL Server only). Note: If you are using NT 4 with SQL Server 7, you will not be able to see the servers when you browse. You should enter the server name in the Datastore server name field. 3. Select the Contributor application in the Name field. Click if you cannot see the application you require. 284 Analyst

Chapter 9: D-Links 4. Select or enter the information as described in the table below: TrustedConnection Select Trusted Connection if this is the method used to connect to the datastore. Trusted Connection requires Windows authentication to be the login method used by the datastore and means that you do not have to specify a login id or password. This method is common for SQL Server datastores and less common but possible for Oracle. This uses the user security of the MTS package that the component is executing within. Use this account Enter the datastore account that this application uses to connect. This field is not enabled if you are using a trusted connection. Enter the password for the account. This field is not enabled if you are using a trusted connection. Click this to give you a summary of the datastore server connection details. Click this to check the validity of the connection to the datastore server.

Password

Preview Connection

Test Connection

5. To configure advanced settings, click Advanced. Typically these settings should be left as the default. These options may not be supported by all datastore configurations. 6. Enter the information as described below. Provider Driver Connection Prefix Connection Suffix Select the appropriate driver for your datastore. Customize the connection strings for the needs of the datastore. Customize the connection strings for the needs of the datastore.

7. Click OK to select the application and return to the D-Link screen.

Analyst<>Cognos Finance Links

You can transfer data between Cognos Finance and Analyst using Analyst's D-Link function. All the standard features of a normal D-Link are available. For example, the use of A-tables, D-Cube allocations, local allocation tables, match descriptions, and matching on codes. There are two types of links available: Analyst>Cognos Finance Cognos Finance>Analyst

User Guide 285

Chapter 9: D-Links

When to Use Analyst <> Cognos Finance Links

Analyst<>Cognos Finance links work in the same way as a standard Analyst D-Link. All D-Link types will be permitted. You can use Match Descriptions, local allocation tables, A-tables, and D-Cube allocations. You can cut subcolumns, letting you match on codes. You can run accumulation links both ways. Note: If you use a saved allocation table and rename when using Cognos Finance as a source or target in a D-Link, the allocation table must be manually updated in order for the link to work like it did before the item was renamed.

Installation
Cognos Finance and Analyst need to be installed and configured before you can run D-Links using Cognos Finance as a Source or Target.

How Analyst <> Cognos Finance Links Work

You set up a Analyst <> Cognos Finance link in the same way as you would a standard D-Link, choosing Cognos Finance Data as the source or target of a D-Link. All the data is prepared in Analyst. The steps for setting up any Analyst<>Cognos Finance link are: In the Analyst D-Link editor, choose Cognos Finance Data as the source or target. Select a Cognos Finance System. Pair dimensions against the target (or source) cube as you would for a normal D-Link.

D-Link Options
If Cognos Finance is installed, the D-Link Options screen will have options for Report Color and Switchable Accounts. These options describe how the Cognos Finance data is retrieved. The parameters for Report Color are Account and Statement. The parameters for Switchable Accounts are Current Month and Year-To-Date.

One-off and Internal D-Links

A one-off D-Link is a D-Link that is only used once or twice; thus, it is not named or saved.

Steps
1. Create a D-Link as normal, but do not name or save it. 2. From the D-Link menu, click Execute.

286 Analyst

Chapter 9: D-Links

Fill a D-Cube with Data Using a One-Off Internal D-Link

Internal one-off D-Links are frequently used to populate a D-Cube with its own data. An internal D-Link is a D-Link that uses the same D-Cube as its source and target. They are often used to copy numbers into new positions so that calculations that would otherwise not be possible may be performed.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click D-Links, Internal. An (unnamed) internal D-Link appears; all source and target D-Lists are paired using match descriptions. 3. Break the appropriate match descriptions pairing: Click the pairing indicator. Click Change to Allocation.

4. Pair the source D-List items with the target D-List items in the local allocation table (p. 242). 5. From the D-Link menu, click Execute.

Date Allocations
This is only available when importing data from a Mapped ASCII file or ODBC database, where a dimension in the source containing dates is matched to a timescale D-List.

Steps
1. Pair a source dimension containing dates with a target timescale D-List. 2. Click Match descriptions. In most cases nothing will appear to match at this point (no source or target items will be selected). But when the D-Link is run, it will recognize the match of a date formatted with a timescale D-List, and instead of a normal match descriptions allocation, the D-Link will perform a date allocation for the dimension pairing. The allocation of source data to the items of the timescale D-List is determined by the From and To dates defined for the items of the timescale D-List defined within the D-List Options dialog box. All data that falls within the date range for a particular item is summed and assigned to that item. Data is only assigned to the first item in which its From and To date range includes the date found in the source. If the source for the D-Link is a Mapped ASCII file, it is essential that the column containing the dates has been marked as Use for selection in the Map editor (defined as a dimension), and that the appropriate date format has been chosen for the column.

User Guide 287

Chapter 9: D-Links

Copy data in a D-Cube from Page to Page

The recommended method for copying data from page to page is to use an internal D-Link. This allows changes of a more global nature rather than copying to and from the clipboard. It also permits a single page to be copied to multiple pages in a single operation, rather than using multiple copy and paste commands. In fact, it allows any range, adjacent to or not, to be copied to any other range of cells.

Steps
1. Open the D-Cube. 2. From the D-Cube menu, click D-Links, Internal. 3. Click the yellow arrow connecting the relevant D-Lists. The default color of the arrow is yellow to indicate that items are matched using a match descriptions pairing (p. 233). By default, all items are matched. 4. Select Change to allocation. This enables you to restrict the source data that will be copied and the data range that it will be copied to. The yellow arrow changes to a green and red arrow, indicating that items are matched using a local allocation table pairing. 5. Select the items to copy. 6. On the Source side, click the D-List item you want to copy. 7. On the Target side, click the relevant D-List item. The allocation table in the center shows how the source and target ranges correspond. Note: If you make a mistake, select the line in the allocation table and press Delete (this action deletes a single line of the table). 8. Repeat with the other items. 9. To copy the range by running the internal D-Link, from the D-Link menu, click Execute. Unlike the copy and paste functions, a D-Link calculates in addition to copying, so that numbers display in red to show that they have changed. 10. From the File menu, click Save.

Update Models Using D-Cube Update List

For Analyst models that are designed for Contributor applications, D-Cube update List is how you must update the Analyst model. An Analyst model collects base data from manual input and from external sources (spreadsheets, databases, and so on), and manipulates it to produce useful report data. The model actually consists of many D-Cubes. Each D-Cube consists of D-Lists that define the set of data held in the D-Cube and the calculations the D-Cube performs. Data in each D-Cube may be input manually, imported from external sources, or imported from other D-Cubes. 288 Analyst

Chapter 9: D-Links When data in a D-Cube changes, the formulas in that D-Cube recalculate automatically. However, the other D-Cubes in your model that are affected by these changes are not recalculated automatically. Similarly, D-Cubes that import data from external sources are not updated automatically when external data changes. Thus, an Update List is necessary. An update list is one method of controlling batches of D-Links run in a specified order that are used to update an Analyst model when data changes (or when the calculations you perform on that data are changed). Each D-Cube can have only one update list. There are cases where different kinds of changes require a different set of D-Links to be run to update a D-Cube. If it is not possible to use one combined update list to update a D-Cube after all changes, you will have to create a number of update macros using the @DLinkExecute macro. In simpler terms, the update list is simply a list of D-Links which should be run (in the specified order) to update a D-Cube. You can save one update list for each D-Cube in your model. After you have saved an update list for a D-Cube, you can update the D-Cube by opening the D-Cube and running the update list. If any D-Links have Contributor cubes as the source, you must execute D-Links from the same data snapshot to prevent inconsistent data reads. You can do this using the @DLinkExecuteList macro, (p. 666). @DLinkExecute runs a specified D-Link. You can create a macro containing any number of @DLinkExecute commands and then run this macro to run the batch of D-Links. Alternatively, you can use the macro command, @DCubeUpdate, which runs the update list for a particular D-Cube. For details, see "Run Batches of D-Links using Macros" (p. 227). If you want to run a batch of D-Links only once, you can run a number of individual D-Links using various different methods, see "Run D-Links" (p. 222). Alternatively, you can use the Library Functions dialog box. Here you can build up a list of D-Links by choosing from those that target particular D-Cubes, and then run them together. You can also a create macro to run batches of D-Links using the macro wizard. See "Create a Macro using the Wizard" (p. 614).

Order of Running D-Links

Often when you update all or part of a model (or just one D-Cube), it is critical that the D-Links are run in a particular order. Perhaps the most common example is where one D-Link brings in the weightings for a break-back allocation (that is, brings in data for detail items in a D-List), and another D-Link brings in the total to be allocated according to these weightings (that is, brings in data for total items in the same D-List). The desired result will only be achieved if the weightings D-Link is run before the totals D-Link. Regardless of the method you use to run batches of D-Links, always be aware that the D-Links are run in the correct order.

D-Cube Update List Dialog Box

The update list for each D-Cube is created and maintained in the D-Cube Update List dialog box. In the Update List dialog box, you choose which D-Links update the D-Cube. Each D-Link included has an entry in the update list. The order the entries appear is the order the D-Links will be run when the D-Cube is updated. User Guide 289

Chapter 9: D-Links A D-Link may be included more than once in the update list (that is, it may have more than one entry), if required. Changes to the D-Cube update list are not saved until the D-Cube itself is saved.

Steps
1. Open a D-Cube. 2. From the D-Cube menu, click D-Links, Update. The D-Cube Update List dialog box includes the following options. 3. In the Execute column, select the D-Links to be executed. Note: Update list can only be used in a Contributor model if this Execute check box is selected. 4. Typically, the calculated cell check box is selected. It recalculates all cells impacted by the D-Link import if selected. This only needs to occur if a subsequent D-Link requires a calculation to be updated. DCubeUpdate runs quicker if this option is turned off but do this with care. It does not calculate cells in target cubes if checked off. Contributor ignores this setting. Click Insert One to insert one D-Link. 5. To insert new D-Links, click one of the following options: Insert One to insert one D-Link. Insert New to identify D-Links not already chosen. Insert All to insert all D-Links.

6. To remove D-Links that no longer target the D-Cube, click Delete Invalid. 7. To remove valid D-Links that target the D-Cube, click Delete. 8. To run all D-Links, click Run All.

Drill Down
Drill down lets you analyze D-Cube data that was imported by a D-Link. You can drill down on any single cell in a D-Cube. If the cell contains data transferred by a D-Link, drill down opens a view of the source data. If the data was imported from another D-Cube, drill down opens the appropriate selection from the source D-Cube. If the data was imported from an external source (a mapped ASCII file or an ODBC database), drill down extracts the relevant data from the source file and displays it in a special drill-down results dialog box. When you drill down to a D-Cube, a selection of the source D-Cube is opened. If the source D-Cube is already open, drill down will open a new view of the D-Cube with the appropriate selection. The source D-Cube opened by drill down is a normal limited selection of a D-Cube. You can, for example, reselect it or print it as usual. You can also drill down on any two-dimensional range of cells in a D-Cube.

290 Analyst

Chapter 9: D-Links

How Drill Down Works

Analyst does not remember where data in a D-Cube originally came from. When you drill down on a cell in a D-Cube, all D-Links targeting the D-Cube are examined to specify the D-Link that targets the cell you drilled down on. If a D-Link targeting the cell is found, Analyst uses the D-Link to determine which source data is assigned to the cell if the D-Link were run. If the D-Link uses a D-Cube as its source, drill down opens a limited selection of the source D-Cube. Only the cells containing the relevant source data are included in the selection taken from the source D-Cube. If the D-Link uses an external source, drill down presents the relevant source data in a special drill down results dialog box. Note: Drill down uses the current D-Links to reveal how source data corresponds with a selection of target data. It does not necessarily show you where a particular number came from.

Steps
1. Open a D-Cube. 2. Select a single cell or a range of cells. If you want to drill down on a range of cells, you must have the appropriate D-Lists in rows and columns. Thus, you may have to slice the D-Cube before you can select the required range. 3. Click the Drill Down button. Drill down will then analyze the data in the selected cells and display the source data in a special drill down results dialog box.

Drill Down on a Cell Using a Source or Mapped ASCII File

If you drill down on a cell that contains data from an ASCII source file, all source data assigned to the cell is shown in the Drill Down Results dialog box. This box does not display all the columns of the ASCII file. The columns not shown are: Columns that have been skipped in the map You can skip entire columns in a file map. Skipped columns do not appear as dimensions in a D-Link, and do not provoke unmatched records. Columns marked Use for selection in the map, which are left with an empty selection in the D-Link (that is, unpaired source dimensions (p. 231) with an empty selection).

All other columns are included.

Drill Down on One Cell Using a D-Cube as a Source

When you click on a single detail cell and then click the Drill Down button, a selection from the source D-Cube is opened.This selection contains all the data assigned to the cell.

User Guide 291

Chapter 9: D-Links

Consideration
Matched source items are included in the selection

Details
Items in the source D-Cube are displayed in the resulting selection after drilling down on a cell. These source items may be paired using match descriptions (p. 233) or a local allocation table (p. 242). All items selected from unpaired source dimensions are included in the source selection (they all contribute data to the cell you drilled down on).

Selected source items are included in the selection

Data taken from a formula If selected items are formula items, the selection is expanded to item in the source expands include all detail items on which the formula items are dependent the formula (either directly or indirectly). By drilling down on formula items, you are effectively drilling down on the dependent detail items as well. You cannot drill down on items outside the open selection When you drill down on a formula item, the drill down range is expanded to include the formula's dependent detail items. However, detail items not included in the open selection of the D-Cube are not included in the expanded drill down range. If you set up a D-Link and leave the source D-Cube with an empty selection and drill down on data transferred by this D-Link, you would not see any subtotals. Subtotals are not automatically given for consolidated data. Multiple source items may be consolidated into one target item by a D-Link. When you drill down on the target item, the selection from the source D-Cube includes only the consolidated source items (and their expansion if they are formula items). Subtotals are not automatically appended in the source D-Cube, even if the appropriate subtotals exist in the D-Lists of the source D-Cube.

Consideration when defining a D-Link

Drill Down on a Range of Cells

When you drill down on a range of cells, the D-Links targeting the D-Cube are examined to see which of them target the cells you drilled down on. If just one D-Link targets the cells you drilled down on, drill down opens one view of the source data. If the data source is a D-Cube, a selection from the source D-Cube is opened. This selection will include all the data assigned to all the cells you drilled down on. If more than one D-Link is found to target cells within the range you drilled down on, a view of the source data is opened for each D-Link that targets cells in the range. It may be that just one source D-Cube provided all the data in the drill down range. In this case, one view of the source D-Cube is opened for each D-Link.

292 Analyst

Chapter 9: D-Links Often, data in the drill down range is transferred from more than one source. The data may have been transferred from D-Cubes, from external sources, or from a mixture of the two. Drill down will open one view of the source data for each D-Link that targets cells in the drill down range. Where data has been imported from D-Cubes, a selection of the source D-Cube is opened. Where data has been imported from an external source, a view of the source data is presented in a drill down results dialog box.

Drill Down on Break Back Allocations

In some cases, one D-Link imports weightings for a break back allocation (it assigns data to detail items in a D-List), and another D-Link brings in a total to be allocated according to these weightings (it assigns data to total items in the same D-List). After the break back, you can drill down on the weightings to see the original weighting data, and on the total to see the total data and all the original weighting data. Consider the following example. In the Weightings D-Cube, weightings for D-List items a, b, c, and d are defined.

Weightings D-Cube
a Sales 40 b 30 c 20 d 10

These weightings are imported into the Weightings and Totals D-Cube via a D-Link. In the Totals D-Cube, the Divisional total is defined.

Totals D-Cube
Totals Sales 1000

When the Divisional total is imported into the Weightings and Totals D-Cube, a break back occurs.

Weightings and Totals D-Cube

a Sales 400 b 300 c 200 d 100 Total 1000

If you drill down on a, only the D-Cube Weightings is identified as the source D-Cube, so drill down presents you with the source weighting, which made up the number 40.

User Guide 293

Chapter 9: D-Links If you drill down on Divisional totals, Analyst identifies both the Totals D-Cube and the Weightings D-Cube as the source cubes. The total formula is expanded, so that Divisional totals is found to assign data to the formula's dependent items; so drill down will present you with the source data, which made up the Divisional total, and the source weighting data, which made up the data in a, b, c, and d.

Troubleshoot D-Links
Most problems encountered when using drill down are due to the presence of invalid D-Links. D-Links may be invalid for various reasons: Drill attempts to trace all D-Links that target the D-Cube. You may encounter problems if obsolete D-Links (that is, D-Links you no longer use) have not been deleted from your model. If you make structural changes to your model (for example, change D-Lists, add, delete or substitute D-Lists in D-Cubes) some D-Links may require editing to bring them up to date. If a D-Link uses an ASCII file as its source, the D-Link will not run if the source ASCII file has been deleted, moved, or opened in another application.

The most common problems encountered using drill down are: Nothing happens when you drill down (p. 294) Error messages appear (p. 295)

The "Nothing to Transfer" Message

You may occasionally see the "Nothing to transfer" message. This message appears when you run a D-Link into an open selection of a target D-Cube that does not include the cells that fall within the target area for a D-Link. For example, a D-Link contains an unpaired target D-List named Months from which one item Q1 Total is selected. When the D-Link is run, the target D-Cube is open with a limited selection from the Months D-List. If the item Q1 Total is not included in the open selection, the above message will be given. Similarly, the D-Link may have the target D-List Months paired using match descriptions. When the D-Link is run, the target D-Cube is open with a limited selection from the Months D-List. If no detail items are included in the open selection, the above message will be given (as match descriptions will not target formula items unless the Match Calculated Target Items box has been checked).

Nothing Happens When You Drill Down

Assuming you have selected the required cell or cells properly before you drill down, either the data in the cell was not imported by a D-Link, or the D-Link that transferred the data can no longer be found, that is, no D-Link is found that targets the cell. There are a number of possibilities: The D-Link that transferred the data has been deleted, or its library has been deleted.

294 Analyst

Chapter 9: D-Links The D-Link that transferred the data is a one-off D-Link (p. 286), that is, it was never saved. The data was transferred by a D-Link run inversely (p. 228). The D-Link that transferred the data has been modified, such that it no longer targets the cell. For example, the relevant item may have been removed from the list of items selected in an unpaired target dimension, or the relevant entry may have been removed from an allocation table. Target D-List items may have changed such that the current D-Link would not assign data to the cell. For example, the relevant item may have been renamed so that it is no longer matched by match descriptions. Source dimension items may have changed such that the current D-Link would not accept data. For example, the relevant item has been renamed in an external source. For an external source, a column may have been added to, or removed from, the source file.

Error Messages Appear When You Drill Down

Error messages that appear when drilling down indicate a problem with one of the D-Links targeting the D-Cube. Remember that when you drill down, all the D-Links targeting the D-Cube are investigated to see which ones target the cells you drilled down. For each D-Link found to be invalid, an error message indicating the nature of the problem is given. Examples of such messages include: "No items match", "Nothing to transfer", "D-List XXX has been deleted from the source D-Cube", and "File not found" (where an external source file has been deleted, moved, or opened in another application).

User Guide 295

Chapter 9: D-Links

296 Analyst

Chapter 10: ODBC Links

ODBC stands for Open Database Connectivity. It is a standard protocol for accessing information in SQL database servers. After installing the relevant ODBC drivers it can be used to import data into Cognos Planning - Analyst from a range of databases, spreadsheets, and other external sources - for example, Access, dBase,Excel, FoxPro, Paradox, Oracle, and so on. The main advantage of using ODBC over importing from text or ASCII database downloads is that you are accessing live data. Because you are importing directly from the data itself, you are not reliant on producing a text copy at the time you wish to import the data. It also saves a step because you do not have to create a file map to define where each column of data starts and ends.

Creating ODBC Links

You can maintain a single version of data between your accounting packages by using ODBC import from your general ledger or accounting package software. You can import items, hierarchies, and calculations, if they are in the Analyst format. To import a D-List from an external data source, you must first ensure that: the correct ODBC driver is installed for the source you want to access the ODBC datasource has been configured within the ODBC Data Source administrator

Install an ODBC Driver

If you do not have the driver you need, you must install it. Generally these will be available on the CD-ROM that comes with the database software. Check their specific manuals for the exact procedure. If you use the 32-bit version of Analyst, you will need the 32-bit ODBC drivers; if you use the 16-bit version, you will need the 16-bit ODBC drivers. From the Help menu, click About to find out which version you are using. The 32-bit version of Analyst and 32-bit ODBC drivers will use 32-bit dynamic link library (.dll) files. Note: For Office 95 drivers, you must create a file in Notepad named SQAPL.ini and save this in the C:\Program Files\...\System directory (where C:\ is the disk Analyst was installed on). This should have the name of each data source in square brackets followed by the lines ExecOnPrepare=Yes and DatabaseType=ODBC.

User Guide 297

Chapter 10: ODBC Links

Set Up an ODBC Data Source

Before you can use ODBC to import data, you must first ensure that the appropriate ODBC drivers have been installed.

Steps
1. From the Start menu, click Control Panel. 2. Double-click Administrative Tools, then double-click Data Sources (ODBC). 3. Click Add to create a new data source. 4. Select the ODBC driver required (such as Microsoft Access Driver (*.mdb)), and then click Finish. For information about using data sources, visit the Microsoft Help and Support Web site.

Import Using ODBC

ODBC is a standard interface that allows you to access and import data from other applications, using SQL as a data access standard to identify the information you want to import. Before you can create the D-Link, you must create a DSN to specify the options, such as the application to which you are connecting or the file that contains the data. You must also specify which columns contain the data in the D-Link.

Import D-List Items into a D-List Using ODBC

You can create a new D-List or insert items into an existing D-List by importing items from a database or spreadsheet using an ODBC link. Before importing D-List items using an ODBC link, you must check that the ODBC driver has been correctly installed and that a data source has been set up for the spreadsheet or database you want to access. The procedure below assumes that you are importing D-List items into a new D-List. If, however, you are importing D-List items into an existing D-List, you must open the D-List, and then from the D-List menu, point to Add Items, and then click Import ODBC. Start at step 3 if using an existing D-List.

Steps
1. From the File menu, click New, D-List. 2. Click Import, and then select Import from ODBC (SQL database). 3. Select an ODBC source, then click Connect. If required, you may need to log on with your ID and password. 4. Select the table and column that contain the items to import.

298 Analyst

Chapter 10: ODBC Links Note: Click Fetch to preview the column. 5. Optional: Click Create SQL to create a SQL statement. Experienced SQL users can edit this statement or type a SQL statement directly into the text box. For example, to combine two columns into a single D-List item, type a SQL expression such as Select ProductID & ProductName from Products. 6. Click OK. 7. Highlight the column to import, and then select Item name in the Select attribute box. 8. If two or more columns were selected to define the hierarchies, formulas are automatically created by selecting the attribute Parent, Parent2, and so on to define the subtotal each item belongs to. 9. Click OK to import the items, and then save and close the D-List.

Import Data into a D-Cube Using an ODBC Link

You may use an ODBC link to import data directly from a database or spreadsheet. Accessing the data directly using ODBC saves you the intermediate step of exporting to a text or ASCII file. If you have not already done so, you must first set up an ODBC data source.

Steps
1. Open the target D-Cube you wish to import the data into. 2. From the File menu, click New, D-Link. 3. Click ODBC (SQL) Database, select a data source, and then click Connect. 4. Select the Display system tables check box. This will give you a list of worksheets. 5. Select a worksheet and highlight the columns containing the data you want to import. 6. Optional: You may click Create SQL to create the SQL statement. You may edit this statement as required (provided you know SQL). You may also click Fetch to get a preview of the columns selected. 7. Click OK. 8. Click Mark Data to select the columns containing the data. 9. Pair the dimensions. 10. When you have finished pairing the dimensions, from the D-Link menu, click Execute. The data is imported using the ODBC link. 11. Save and close the D-Link.

User Guide 299

Chapter 10: ODBC Links 12. If you do not intend to use the ODBC sources again in the current session, from the File menu, click Close ODBC.

300 Analyst

Chapter 11: Libraries

A library contains a group of connected objects. The types of objects available are macros, reports, D-Links, selections, D-Cubes, maps, A-Tables, D-Lists, and formats. In spreadsheet terminology, a model is comparable to a series of connected worksheets. In Cognos Planning - Analyst, a model is a group of D-Cubes connected by D-Links with all associated D-Lists and other objects. A model might contain objects which are stored in several different libraries. Alternatively, objects in one library may be used by several models. An example of this would be where common D-lists are stored in a library accessed by several users, each of which operates their own model using the D-Lists. Groups of D-Cubes and D-Links can be copied (p. 310) from one library to another. A common reason for creating a new library is to store a different version of a model. Not only can a single user have several libraries of their own, each with its own models or versions of the same model, but the libraries can also be spread over a multi-user system.

Examples: Use of Separate Libraries

You can have a library for actuals, another library for the budget, and another library for the variance. The libraries containing actual, budget, and variance are essentially different versions of the same model and will most likely have shared D-Lists throughout. A second example of using libraries is to archive a model. You can take last year's model and copy it to a separate library for storage and reference only. Because the list of account codes may vary from year to year, you may want to keep the account code D-Lists independent of each other so that you can delete obsolete codes without fear of losing data. A third example of the use of libraries is to distribute parts of a model to subsidiaries to work on their own particular part of the budget. When you need to consolidate the budget, you can combine the data from the subsidiary models and the satellite libraries into a single central library.

Work with Libraries

Only a system administrator may add or delete libraries or change their properties. Users belonging to users, groups, and roles which are not System Administrator will see a list of the libraries to which they have at least Read level access, but they will not be able to change their properties. System administrators can import and export libraries into development, test, or production environments using the deployment wizard in the Contributor Administration Console. For more information about deployment, see the Cognos 8 Planning - Contributor Administration Guide.

User Guide 301

Chapter 11: Libraries

Library Administration
The library administration screen lets you add, remove, rename, print, and set security and access rights on libraries. It contains all of the libraries currently available in Analyst. From the File menu, select Administration and then click Maintain Libraries and Users. Sort by clicking on Column headings. Click Add and Remove to add or remove libraries. Select a library and click Print table to print a table of all of the libraries, their numbers, paths, and owners. Right-click a library and select Print all security information to print the security that is set up for every library. Right-click a library and select Print security information for selected item to print the security for a specific library. Click Properties to set the library name, description, path, and access rights. Click Browse to search and replace the path for libraries in Analyst.

Create a Library
Create a library to store different versions of a model. You can create a separate library for each model in a system, and each library will have a separate folder in the Windows directory. If you are developing a model that will not be used to create Contributor applications, the D-Cubes for the model must be in a self-contained library. The e-List and D-Links must be in the same library. The other objects, such as D-Lists, can be distributed to one other library.

Steps
1. From the File menu, Administration, Maintain Libraries and Users. 2. Click the Libraries tab, and then click Add. 3. In the Add New Library dialog box: Enter a library number in the Library No.text box or leave the Library No. text box blank to generate a library number automatically Enter the name of the library. Enter a description. Enter the path of the library. Click OK.

4. Click Close.

302 Analyst

Chapter 11: Libraries

Delete a Library
When you delete a library, you can no longer use the contents of that DOS directory although the underlying DOS files are not deleted. Care should be taken before deleting a library.

Steps
1. From the File menu, click Administration, Maintain Libraries and Users. 2. Click the Libraries tab, and then select a library. 3. Click Remove. 4. At the prompt click Yes. 5. Click Close.

Display Library Name

You can choose to show the library name so that you can verify that you are working with the correct library for your model.

Steps
1. From the Tools menu, select Options and click the View tab. 2. Select the Display library information in caption of object editors check box. This will display the library name in the title of each D-Cube, D-List or other object. 3. Click OK.

Change Library Details

You can change the name, description and location of the library that is used for your model. To secure access to the library, you can also change Users, Groups and Roles.

Steps
1. From the File menu, click Administration, Maintain Libraries and Users. 2. Click the Libraries tab, and then select a library. 3. Click Properties. 4. In the Properties dialog box, edit the name, description, or path. 5. Click the Access tab to change the access rights to the library. Note: The library number can not be changed. 6. Click OK. 7. Click Close.

User Guide 303

Chapter 11: Libraries

The Library Window

You can access the library by clicking File, Library, Objects. Limited sections of the library can be used by selecting one type of object only. For example, to access the library section focused on D-Cubes, click the File, Library, D-Cubes.

Rename an Object
You can rename an object so that it better reflects the library to which it belongs. You can also move selected objects to a different library under the same or new name. If an object is already open by another user, it cannot be renamed. If you attempt to rename an open object, you will receive the message stating
Cannot move/rename, object(s) in use: Conflict with user Administrator

Before renaming an object using a library, you must first save and close the object. You have to close the object before attempting to rename it.

Steps
1. From the File menu, click Library, Objects. 2. Select the objects that you wish to rename, and then move them to the Objects Selected box by clicking the down arrow. 3. Click the Rename/Move button, and then type in a new name. References to the object's new name are remapped automatically. You do not need to change the cross-reference options when renaming objects, so the remap options To, Between, and From are dimmed. 4. Click OK. Note: If you select a different target library, then the objects selected will be moved to a different library. Any references to the object will be updated accordingly. 5. Click Close.

Delete an Object
Delete an object when it is no longer required in the library. If the object is being used by D-Links, macros, reports, or selections, then these other objects must be deleted or edited first. You may show the various uses of an object using the Show dependants and precedents feature. The dependants of an object are the objects it uses. Showing the dependants shows the constituent parts that make up an object. To use an analogy, the dependants of a car are its chassis, wheels, engine, and so on. The dependants of an engine are the valves, overhead cams, pistons, and so on. For example, a D-Cube depends on its D-Lists. A D-Link depends on both the source D-Cube and the target D-Cube. A D-List may depend on a format to apply to one of its D-List items.

304 Analyst

Chapter 11: Libraries Showing the precedents shows the various uses of an object. To use an analogy, the precedents of a wheel are a car, bus, train, and so on. For example, a D-List can be used by several D-Cubes, and the precedents of a D-List are all the D-Cubes it is used by.

Steps
1. From the File menu, click Library, Objects. 2. Select the objects that you wish to delete, and then move them to the Objects Selected box by clicking the down arrow. 3. Click the Delete button. The object will be deleted provided it is not in use elsewhere. A message will appear informing you of the usage of the object. 4. To display other objects that are dependent on a particular object, click the Show objects that the selected object(s) is using button. 5. To display other objects that a particular object is used by (precedents), click the Show objects that the selected object(s) is used by button.

Move an Object to a Different Library

When you move an object, references to and between objects will be remapped automatically. For example, if you move a D-Cube, it will still refer to the D-Lists in the original library unless these are moved at the same time. You are only allowed to alter the To, Between and From reference settings when copying, not when moving or renaming.

Steps
1. From the File menu, click Library, Objects. 2. Select the objects that you wish to move, and then move them to the Objects Selected box by clicking the down arrow. 3. Click the Rename/Move button, and then select the library to which you want to move the object. The object will be moved to the new library. 4. Click OK. 5. Click Close.

Show the Precedents of an Object

You can show the precedents of an object, which are the other objects that use it.

Steps
1. From the File menu, click Library, Objects. User Guide 305

Chapter 11: Libraries 2. Select an object. 3. Click the Show objects that the selected object(s) is used by button, or right-click the object, and then click Show Used By. The objects using your object (the precedents) are displayed. 4. Optionally in the Usage area, you can select the objects by type of usage. 5. Optionally, the highlighted objects can be selected by moving them to the bottom list using the down arrow button. Then they can be opened, run, copied, moved/renamed, printed, or deleted using the buttons provided. 6. To return to the library, click the Back button.

Show the Dependants of an Object

You can show the dependants of an object, which are the objects it uses.

Steps
1. From the File menu, click Library, Objects. 2. Select an object. 3. Click the Show objects that the selected object(s) is using button, or right-click the object, and then click Show Using. The objects used (the dependants) are displayed. Note: If an object in one library is dependent on an object in a different library, you must have access rights to both libraries before making changes to the objects. If you do not have access rights to both libraries and try to modify the objects, they can cause errors. To avoid this, either change your access rights, or manually set the object level security access on the objects. 4. Optionally, in the Level area, you can click the level buttons to look at the level of dependency. 5. Optionally in the Usage area, you can select the objects by type of usage. 6. Optionally, the highlighted objects can be selected by moving them to the bottom list using the down arrow button. Then they can be opened, run, copied, moved/renamed, printed, or deleted using the buttons provided. 7. To return to the library, click Back.

306 Analyst

Chapter 11: Libraries

Highlight Unused Objects in the Library

Unused objects are objects not used by other objects. In general, these objects are macros, reports, and occasional D-Links because they are at the top of the hierarchy of objects. You can easily view which objects are not used in a library.

Steps
1. From the File menu, click Library, Objects. 2. Right-click an object and then click Highlight unused objects. All unused objects will be highlighted.

Reveal the DOS File Name

The DOS file name may be viewed by the system administrator only.

Steps
1. From the File menu, click Library, Objects. 2. Right-click an object and click Reveal File Name. The full DOS file name will display. 3. Click OK to return to the library.

Show the Description of an Object

The description of an object is entered by clicking the File menu, and then clicking Summary Info. You may view an object's description in the library.

Steps
1. From the File menu, click Library, Objects. 2. Right-click an object and click Show Description. The description is shown on the screen. 3. Click OK to return to the library.

Copy Objects
Objects may be copied to different libraries or within the same library under a different name. When copying objects, references to, from, and between objects may need to be remapped.

User Guide 307

Chapter 11: Libraries In the library, if you copy a D-Cube over an original D-Cube of the same name, you have the option to use the data from the original or the copy.

Steps
1. From the File menu, click Library, Objects. 2. Select the objects that you wish to copy, and then move them to the Objects Selected box by clicking the down arrow. 3. Click the Copy selected objects button. 4. In the Target Library area, select the library to copy to. If copying to the same library, a new name for the object is required. By default, references between copied objects are remapped. 5. Make your selection in the Remap references to/from selected objects area. 6. To prevent original data from being overwritten, select the Do not overwrite existing D-Cube data check box. This copies the D-Cube structure, not the data. The D-Cube structure comprises reference tables referring to D-Lists and D-Links as well as D-Cube formatting. The structure is stored separately from the data. 7. Click OK.

Remap Objects
When D-Cubes and other objects are copied, references to and from other objects may need to be remapped. In spreadsheet terminology, the concept is similar to copying relative addresses when copying formulas. However, the scale is much larger. You are doing the equivalent of copying whole groups of worksheets with formula references to other worksheets. When a D-Cube is said to refer to its D-Lists, it is another way of implying that a D-Cube is dependent on its D-Lists. The D-Cube is said to have references to its D-Lists, but the converse is not the case. A D-List does not depend on a D-Cube for its existence. It can exist on its own. Similarly, a D-Link is said to refer to its source and target D-Cubes. D-Lists do not usually refer to any other objects (except formats) but have references from their D-Cube. Note: The words, To and From, do not mean links to and from a D-Cube. In fact, the references, To and From, have nothing to do with the direction of data flow, but indicate which object uses other objects. The rule of thumb for remapping references To copied objects: If To is selected, then objects use the copies. If To is not selected, then objects continue to use the originals. By default, To is not selected. The rule of thumb for remapping references Between copied objects:

308 Analyst

Chapter 11: Libraries If Between is selected, then copied objects refer to each other. If Between is not selected, then copied objects refer back to the originals. By default, Between is selected. The rule of thumb for remapping references From copied objects: If From is selected, then copied objects refer to objects in the library they are copied to. It is used when copying higher level objects such as D-Links when you know that the target library already contains the dependents of the copied object. If From is not selected, then copied objects refer to their original dependents. By default, From is not selected.

Check Integrity
Check Integrity allows you to check to see if a group of objects is self-contained, or whether it needs other objects to function. Check Integrity checks for missing objects, then classifies them as: Required The set of selected objects will not work as a model without required objects. For example, if you select a set of D-Cubes, it will look for all the D-Lists required for the D-Cube to be opened. It will then go all the way down the tree, looking for formats and other D-Lists used by the first set of D-Lists until it has all the objects it needs. These objects are the Required set of objects. Suspects Suspects are objects that refer to your selection, but also to other objects. For example, if you select a set of D-Cubes, then the D-Links between these and other D-Cubes outside your original are Suspects. You might or might not want them. If you do select Probables or Suspects, the program looks again to see if you now need other Required objects that you did not need before. Probables Probables are objects that refer only to your particular selection. For example, if you select a set of D-Cubes, then the D-Links between these are classified as Probables. Selecting Probables will help your model to be more useful, however, they are not essential. You can still open the D-Cubes without the presence of the D-Links that join them. Check Integrity is also useful for checking that a library is complete, particularly when generating a Contributor template. It is also very useful if you have inadvertently used objects from other libraries and want to check which libraries are referenced. It can also be used to extract a copy of a self-contained sub-model to send to someone else.

Steps
1. From the File menu click Library, Objects. User Guide 309

Chapter 11: Libraries 2. Select the library you require and then click the objects you wish to test. 3. Click the down arrow to move the objects to the lower screen. Objects from different libraries can also be selected. After choosing the objects from the first library, simply use the drop down box to select the next library and then select the objects you require. 4. Start Check Integrity by clicking the Check Integrity icon. To get a printable report containing details of the references of the selected objects, right click on the objects in the lower selection screen and select Check Integrity.

Open Multiple Objects

This is a useful way of selecting several objects to open at once. If the required objects are in different libraries, then make your selection from the first library before changing the library from the drop-down box and selecting the objects required from the next library.

Steps
1. From the File menu, click Library, Objects. 2. In the Library window (p. 301), select the object and move it to the bottom with the down arrow button. 3. Click Open objects. 4. To exit the Library Functions dialog box, click Close.

Copy Libraries or Objects Using the Library Copy Wizard

You can use the Library Copy wizard to copy a single library, a set of inter-linked libraries, or a series of objects. The library copy wizard is designed to help users who have large complex models that span several libraries. For example, if you require a year-end rollover, you may need to copy a set of libraries as a set, and zero it for next year's budget. Or, if you are creating a Cognos Planning - Contributor template, you may want to check that the library is self-contained and not missing any objects that would prevent the application from being created. The Library Copy Wizard also lets you: Make multiple copies of a single library. Make multiple copies of a set of libraries, preserving the relationships between the libraries as a set. Copy a sub-model from part of an existing library, ensuring that it is a self-contained unit. Merge several libraries into one. Duplicate a set of objects within a library, renaming according to a convention you define.

310 Analyst

Chapter 11: Libraries Copy one library into another, replacing the original. Copy a subset of objects into another library. Check that a library or a set of libraries is self-contained and does not require outside objects in order to work.

Steps
1. From the File menu, select Library and then click Copy to bring up the Welcome to the Copy Wizard screen. 2. Click Next to bring up the Libraries or Objects screen. 3. Choose whether to copy libraries or objects: To copy single or multiple libraries, click Select Libraries, and click Next (p. 311). To copy objects, click Select Objects (p. 312).

Select Libraries
You can copy a single library or multiple libraries. The instruction for selecting a single library differ from those for selecting multiple libraries.

Steps
1. In the Select Libraries to Copy dialog box, select the check box for each library that you wish to copy, and click OK. Note: If the selection does not have the required objects necessary to function, an information box appears asking if it should include the missing objects. Click Yes or No, or Cancel to redo the selection. 2. If you selected a single library and the Merge to Single Target Library check box, choose how you want to manage the copy process: Create New Libraries (p. 312). Duplicate (p. 313). Copy into Libraries (p. 314). Replace Libraries (p. 314).

3. If you selected multiple libraries and cleared the Merge to Single Target Library check box, choose one of the following options: Create New Libraries (p. 312). Duplicate (p. 313).

4. Select the number of copies you want to make, and click Next.

User Guide 311

Chapter 11: Libraries

Select Objects
The Select Objects option lets you copy individual objects like D-Lists or D-Cubes.

Steps
1. In the Select Objects dialog box, choose how you want to select the objects you want to copy: To select an object, double-click the object. This moves the object to the bottom pane. To select a type of object and reduce the number of different items shown to just one type of object, click the Select a Datatype drop-down list. To show every object in the current library, click All. To search for an object, click the Find Objects button. You can use wildcard characters, And and Or boolean operators, match case, and exact name features to refine your search. To view specific precedent or dependents, you can click Show object(s) that the selected objects is used by button or the Show objects that the selected object(s) is using button, and click OK. In the Show Dependents or Objects Using dialog box, click the Highlight Usage Type to select dependents or objects based on their function to the D-Cube. 2. To print selected objects, right-click an object and select Print List of objects. General information, including security access, owner's notes, and the name of the DOS file is printed. Specific information about the object and its dependents include details of calculations and formats used by D-Lists, the names of the D-Lists used by a D-Cube, and the mappings of D-Links. 3. Click OK. 4. In the Copying Library (s) dialog box, choose one of the following four choices Create New Libraries (p. 312). Duplicate (p. 313). Copy into Libraries (p. 314). Replace Libraries (p. 314).

5. Click Next.

Create New Libraries

The Create Libraries screen prompts you to verify or change the library numbering, naming or renaming of libraries, and where to create the new libraries. Make the necessary changes. Suggestions for the name, path and library number are made by the wizard, although you can override these.

312 Analyst

Chapter 11: Libraries You can select the first library number to use and library numbers for the other copies are generated automatically. The default name for the windows directory is l followed by the library number (E. g. l811), but you may change this, or Browse for an existing path. A blue mark against a library name indicates that it is too long (more than 31 characters) or that it conflicts with an existing library name. A red mark indicates that the library number is already in use. The Restrict Copy screen allows you to remove objects from the list of actual objects to be copied. This is generally used if you only want to copy a subset of the objects previously copied. If you wish to remove objects from the list, you can click the Reduce Selection button, otherwise you can click Next. Note: Although you normally will not reduce the selection, the use of Reduce Selection is important. It allows you to make changes if you made an error in the original source library and did not discover it until later. Primarily it covers the case where you are updating libraries that were already copied at an earlier date and you now want to copy in some amendments. The amendments affect some, but not all of the objects originally copied. You want the amended objects to be fully integrated into the target libraries. Reduce Selection ensures that references to objects that are not copied will be moved to the target library, under the assumption that there are objects that are already there. For example, suppose you make multiple copies of a library, and at a later date, you find an error in a macro included in the original library. You correct the macro in the original source library and now want to copy it into all the copied libraries. If you just copied the macro into the target library on its own, it would continue to refer to objects in the original library it came from, which would be useless. However, if you make as if to repeat the original copy operation and at the last screen reduce the selection down to just the single macro, (using Reduce Selection) then it will correctly refer to the objects in the target library(s) and not those in the original. So if you copy the entire library, at the last screen reduce the selection down to just the one macro, it will copy the macro into the target library(s) and refer to the objects in the targets rather than referring back to the original library. The Confirm Copy screen asks you to verify that the information is correct. The Confirm Copy screen also informs you exactly what actions will take place based on your selections. If the information entered is correct, click Finish to start the actual library copying.

Duplicate
The Duplicate selection allows you to create copies in the original libraries, and choose how many copies to make. You can use the Resolve Name Conflicts screen to change the target name of an object, apply a prefix or suffix to selected rows, and identify conflicts. This gives you the option to overwrite conflicts by selecting the Overwrite conflicting objects in target libraries check box. When you duplicate objects within a library or copy objects into an existing library, there is a potential for a name conflict. Fortunately, most of the name conflicts are resolved for you by the library copy wizard. Because two objects can not have the same name, the wizard will automatically add a prefix to the object with Copy1_, Copy2_ and so on. You have control over the prefix or suffix required to resolve any name conflicts. To rename manually, right-click the name then select Rename.

User Guide 313

Chapter 11: Libraries If you see a red marker against a name, it means that it conflicts with a name in the target library. Usually you should pick another name. A blue marker against a name indicates it is longer than the 32 characters allowed. Click Truncate to cut it down to 31 characters. A green marker indicates there is no name conflict. One way of resolving name conflicts is to apply a prefix or suffix. To apply a prefix (or suffix), first type the prefix in the text box provided, then highlight the objects, and finally click the Prefix (or Suffix) button. Optionally, you can overwrite objects of the same name in the target library. If you want to replace target objects of the same name, select the Overwrite conflicting objects in target library check box. If you add a Prefix or Suffix, or select the Overwrite conflicting objects in target library check box, click Next to go the Restrict Copy screen; otherwise click Back to return to the Copy Library screen. The Restrict Copy screen allows you to remove objects from the list of actual objects to be copied. This is generally used if you only want to copy a subset of the objects previously copied. If you wish to remove objects from the list, click Reduce Selection, otherwise click Next. Note: You normally will not reduce the selection. The Confirm Copy screen asks you to verify that the information is correct. It also informs you exactly what actions will take place based on your selections. If the information entered is correct, click Finish to start the actual library copying.

Copy into Libraries or Replace Library

The Copy into Libraries and Replace Library selections allows you to target existing libraries. You can select the target library or libraries from the list, or Ctrl or Shift+Click to select multiple libraries. Use the Resolve Name Conflicts screen to change the target name of an object, apply a prefix or suffix to selected rows, and identify conflicts. This gives you the option to overwrite conflicts by selecting the Overwrite conflicting objects in target libraries check box. If you add a Prefix or Suffix, click Next to go the Restrict Copy screen, otherwise click Back to return to the Copy Library screen. Note: If you have any name conflicts, an information message will appear prompting you to either change names or overwrite conflicting objects in the target libraries. Clicking OK returns you to the Resolve Names Conflict screen. The Restrict Copy screen allows you to remove objects from the list of actual objects to be copied. This is generally used if you only want to copy a subset of the objects previously copied. If you wish to remove objects from the list, click Reduce Selection, otherwise click Next. Note: You normally will not reduce the selection. The Confirm Copy screen asks you to verify that the information is correct. It also informs you exactly what actions will take place based on your selections. If the information entered is correct, click Finish to start the actual library copying.

314 Analyst

Chapter 12: Built in Functions (BiFs)

A Built in Function (BiF) is a special calculation formula that has been set up specifically for complex planning functionality. A few examples of BiFs include depreciation, discounted cashflow, forecasting using different drivers, and stock purchase prediction based on future sales. BiFs are similar to the financial functions used in spreadsheets such as the @ functions in Lotus. However, unlike spreadsheet @ functions, BiFs cannot be nested into other calculation formulas, nor are they typed directly into a cell. Instead, they are entered as special calculation functions into a single item in a D-List. Only one D-List in a D-Cube can contain BiFs, namely the D-List containing calculations (not the timescale D-List). BiFs become active in the calculation D-List only when created with a timescale D-List in a D-Cube. An example of a BiF is @Feed. It is used to feed the ending inventory from one period to the beginning inventory of the next. This cannot be done using a normal D-List formula because the inputs to the formula are in a different row and column from the result. Normal formulas refer to items in the same row or column, with no cross-referencing allowed. But the formula that is needed here could not be generated without using a BiF because it cross-references cells that are not in the same column.

BiF Library
The BiF library compliments the Analyst User Guide functionality by providing working examples of all Built in Functions. It is optionally installed with the software. Note: If you do not have access to the library, please contact your System Administrator. This self-contained BiF library may be accessed using Cognos Planning - Analyst, however a Cognos Planning - Manager front end has been provided to simplify navigation. There are three reports included in the BiF library - Menu 1, Menu 2, and Menu 3. They are linked together and provide links to the appropriate D-Cubes. In the case of the Forecast BiF, a graph has also been provided to further explain the impact of the different methods available. The BiF library contains a D-Cube for each BiF. Each D-Cube in the BiF library consists of a minimum number of dimensions, enough to demonstrate functionality only. When working with your own D-Cubes, it is likely that they will contain more dimensions than those demonstrated in the library. Where ever possible, the D-Cube data supplied in the BiF library mirrors the data examples in the user guide to further integrate the BiF library and the Analyst User Guide. D-Cubes in the BiF library should therefore not be saved following any changes. Where appropriate, annotations have been provided to further explain the data provided. Note: If you wish to utilize a specific BiF, it is recommended that you do not use the D-Lists in the BiF library, but rather create new D-Lists using one of the following options: From the File menu, click Save As to create a new D-List in the library in which you intend to use the BiF.

User Guide 315

Chapter 12: Built in Functions (BiFs) Import required items from the BiF D-List.

It will also be necessary to make copies of any D-Lists used as D-List formats and Saved formats, pointing the BiF D-List to the new format D-List or Saved Format.

Work with BiFs

The following are the many actions that can be taken with BiFs.

Steps to Create a BiF

1. Create a D-List containing the BiF parameters. The D-List items required for each BiF are listed in the BiF examples (p. 320) section. 2. Click the Calculation cell of the item to which you want to apply the BiF. 3. Click Change item attributes. 4. Click BiF. 5. From the Function Name box, select a BiF. 6. Click Next. 7. In the Items list, double-click the D-List items to select the parameters. Occasionally, a character string or a number is required as a parameter rather than a D-List item. After you select an item for the first parameter, the cursor advances to the next parameter. 8. Click Finish. 9. Click Apply. The BiF calculation generates automatically. 10. Save the calculation D-List. Once you have entered the BiF formula in the calculation D-List, you need to set up time averages (p. 106) or weighted averages (p. 106), set up a timescale D-List, and create a D-Cube using calculation and timescale D-Lists. Ensure that you select the D-List containing the BiF result first.

Steps to Edit a BiF

1. Open the D-List that contains the built in-function (p. 315). 2. Click the Calculation cell of the item that contains the BiF. 3. Click Change item attributes. 4. Type the BiF information accordingly. Be careful to match the syntax.

316 Analyst

Chapter 12: Built in Functions (BiFs) The function itself is contained in the format @BiFname(parameter1;parameter2; parameter3) . Each parameter is separated by a semicolon (;) and the entire function is enclosed in normal mathematical parentheses ( ). D-List items that contain more than one word are in braces { } within the function. 5. To test the syntax, click Apply. 6. Save and close the D-List. If you want to test a formula result before saving it, click Implement from the D-List menu to verify the formula. If a mistake occurs, click Reset from the File menu to reset the D-List to its saved version.

Steps to Delete a BiF

1. Open the D-List that contains the built in function. 2. Click the Calculation cell of the item that contains the BiF. 3. Click Change item attributes. 4. Click Clear. 5. Save and close the D-List.

BiF Results
The result of a BiF formula displays in the Calculation column of a single D-List item. For example in the @Feed BiF, the BiF result is calculated and entered in the Ending Inventory balance.

Item Name
Ending Inventory

Format

Calculation
BiF

Calc. Option
Last Period

Text Shortage Text

Conditional

Ending Inventory = @Feed(;{Beginning Inventory};Purchases;{Cost of Goods Sold}) In the D-List editor, the calculation field for any D-List item which is the result of a BiF will display the word 'BiF'.

BiF Outputs
BiF outputs, typically opening and closing balances, are other calculations created by a BiF.

User Guide 317

Chapter 12: Built in Functions (BiFs) You do not need to enter output formulas in the calculation screen; they are generated automatically when you create the BiF. For example, in the @Feed and @Delay BiFs, the BiF output is calculated in the item, Beginning Inventory. It is equal to the Ending Inventory from the previous time period. Beginning Inventory = @From(Ending Inventory) You cannot edit the BiF output, but you can remove it by editing it out of the BiF calculation so that the BiF result is Ending Inventory = @Feed(;Purchases; Cost of Goods Sold). Optionally, you can delete the D-List item, Beginning Inventory, and the Ending Inventory balance still calculates correctly. The BiF stores the outputs as internal variables and does not need to display them on the screen to calculate them correctly. You cannot edit formulas in D-List items containing outputs from BiFs. The program dims the calculation screen containing BiF outputs to indicate that you cannot change the formula. In the example used below, a BiF named @Delay has been set up. The Closing balance contains a BiF output formula generated as a result of setting up the BiF in the Cash paid D-List item.

Closing Balance = @From(Cash Paid) Similarly the Opening Balance is also a BiF output calculated from the closing balance of the previous period. Opening Balance = @From(Closing) In the example shown, the @Delay BiF uses both Opening and Closing Balances as BiF outputs. @Delay({Year-end Balance};{Opening Balance};Invoice;{Closing Balance};{%This Period};{%Next Period};{%Period +3}; {%Period +4})

Remove a BIF Output

Optionally, you can remove BiF outputs from a formula. You can then use the D-List items to calculate something else or delete them from the D-List entirely. For example, to save memory usage in large D-Cubes. The BiF still calculates correctly because it stores equivalent variables internally and does not need to display BiF outputs on the screen.

Steps
1. Open the D-List that contains the built-in function. 2. Click the Calculation cell of the item that contains the BiF.

318 Analyst

Chapter 12: Built in Functions (BiFs) 3. Click Change item attributes. 4. Click BiF. 5. Clear the parameter. In this case, Opening Balance is cleared. 6. Click Finish. The parameter is deleted from the calculation. 7. Click Apply.

Priority of Calculations
BiF results must be calculated before adding across time periods or summing other dimensions. The simplest way to achieve this is to order the D-Lists in a D-Cube so that the D-List containing the BiF calculation comes first. Calculations in the later D-Lists are always calculated last.

Circularity in BiFs
Circular arithmetic is not allowed in built-in functions. If a circular equation is mistakenly created, the items responsible for circularity will disappear from the selection screen rather than indicate that the formula is circular. For example, if Ending Inventory is a function of Beginning Inventory, Purchases, and Cost of Goods Sold; then these items must be independent; thus, Purchases can not be a function of Beginning Inventory as this would lead to circular arithmetic. If you set up a calculation as shown below, circular arithmetic is not allowed: Ending Inventory = @Feed (0;{Beginning Inventory}; Purchases; {Cost of Goods Sold}) Beginning Inventory = @From {Ending Inventory})

For example, the following formulas would not be allowed: Beginning Inventory = Cost of Goods Sold + Purchases Cost of Goods Sold = Beginning Inventory * 0.8 Purchases = Beginning Inventory * 0.75

It can be argued that the formulas for Beginning Inventory and Ending Inventory are themselves circular because Ending Inventory = Function(Beginning Inventory) and Beginning Inventory = Function(Ending Inventory). This anomaly is resolved when you consider the time element in the equation. Beginning Inventory is equal to the Ending Inventory from the previous period, not the current period. Thus, the arithmetic is not circular. Note: To view any syntax or other error details, from the Help menu, click Show Calculation Errors.

Nesting in BiFs
Nesting of built-in functions within other formulas is not permitted. This means that you cannot use BiFs directly within another calculation formula. Consider the following: User Guide 319

Chapter 12: Built in Functions (BiFs) Adjusted Closing Balance = @Feed( 0; Open; In; Out) + Adjustment Adjusted Closing Balance = @Feed( 0; Open; @YTD(Sales) ; In, Out)

However, D-List items that contain BiF results or outputs can be used in other formulas. Adjusted Closing Balance = {Closing Balance} + Adjustment

Breakback in BiFs
Because of the complex nature of some of the formulas in built-in functions, setting targets using breakback is not possible. If you mistakenly enter data into the result cell of a built-in function the numbers do not change.

BiF Input Parameters

BiF input parameters are the inputs used to calculate a result. They can be D-List items, numbers, or characters that are used as variables in the BiF formula. BiF parameters are separated by a semicolon (;) in the BiF equation. However, BiF parameters are not always D-List items. Sometimes they are numeric or character codes used to change the treatment of time in the BiF calculation. You can also use constants as input parameters rather than D-List items.

Show Calculation Errors

To view any syntax or other calculation errors, click Show Calculation Errors from the Help menu.

BiF Examples
Overview of Examples
The following table summarizes the examples detailed below the table. Cycles (p. 324) Days (p. 327) Calculate seasonal factors from known Fourier form coefficients. Returns the number of days in each period by referring to the dates defined in the timescale D-List. Allows you to set the period length directly in the D-Cube by using the parameter Days in Period. Discounted Cash Flow. Decumulates a series of data. Delay of invoice receipts/payments. Calculates closing debtor or creditor balances based on payment profiles.

DaysOutstanding (p. 328)

DCF (p. 331) Decum (p. 336) Delay (p. 337)

320 Analyst

Chapter 12: Built in Functions (BiFs)

DelayDebt (p. 340)

Calculates receipts from past sales based on debtor days, or payments based on creditor days. Calculates purchases to cover future demands. Allows you to have time periods of variable length in a timescale D-List. Diminishing balance depreciation. Straight-line depreciation. Sum-Of-Year-Digits depreciation. Calculates original series from year-to-date figures. Calculates difference between current and previous period. Forecast based on one or more drivers. Single driver forecast. Two driver forecast.

DelayStock (p. 343) DepnAnnual (p. 346)

DepnDB (p. 352) DepnSLN (p. 355) DepnSYD (p. 356) Deytd (p. 359) Differ (p. 360) Drive (p. 362) Drive1 (p. 365) Drive2 (p. 368)

ErlangDelayAgents (p. 371) Returns a calculation for the number of agents that are required to meet call center service level. ErlangDelayFull (p. 373) Returns a calculation for the proportion of calls that will be queued because there are no agents available when the call was answered. Similar to ErlangDelayFull, except is performs fewer calculations for its output. Returns a calculation for the proportion of calls that find all lines busy in a system with no queue and one line to each agent. Feeds closing balance of one period to the opening balance of the next. Feeds closing balance of one period to the opening balance of the next and calculates overflow as a function of the opening balance. Combines actual and forecast data to produce a rolling forecast. Use of, or source of funds.

ErlangDelayLite (p. 375)

ErlangLossLite (p. 375)

Feed (p. 379)

FeedParam (p. 380)

Forecast (p. 383) Funds (p. 394)

User Guide 321

Chapter 12: Built in Functions (BiFs)

FV (p. 395) Grow (p. 406)

Future value or balance of the account at the end of the periods. Grows a base figure by a specified percentage each period. It can be compound or linear. Inflated cashflow. Internal Rate of Return is that rate for which NPV is equal to zero. Lag (or lead) calculates invoice payments or receipts by delaying a number of periods from the date of invoice. Looks back along a series of data in the input row and returns the most recent non-zero value. Lease calculates a payment schedule for a lease, loan, mortgage, annuity or savings account. Lease allows a series of accounts to be scheduled along a timescale, but each account must have a specified start and end value and run for a specified number of periods. LeaseVariable calculates a payment schedule for a lease, loan, mortgage, annuity or savings account. LeaseVariable allows you to schedule an account along a constant periodic timescale but allows considerable flexibility in the behavior of the account. Linear Average. Mixes historic actual data prior to the switchover date with a forecast at and after the switchover date.

ICF (p. 408) IRR (p. 411) Lag (p. 418)

Last (p. 421)

Lease (p. 423)

LeaseVariable (p. 443)

LinAvg (p. 472) Mix (p. 473)

Movavg & Movsum (p. 475) Calculate a moving average or moving sum over specified periods. Movemed (p. 481) Takes the median value after sorting all input values into ascending sequence. The number of periods over which the account is defined. Net Present Value is the sum of a series of cashflow values each discounted to the period where NPV is calculated based on the rate input by the user in that period. Year end outlook calculation. Revises forecast to meet plan. The payment or fixed amount applied to the account each period.

Nper (p. 484) NPV (p. 493)

Outlook (p. 498) PMT (p. 501)

322 Analyst

Chapter 12: Built in Functions (BiFs)

PV (p. 509)

The Present Value or balance of the account at the start of the period. Allows you to enter a start and stop date and express the length in days as a proportion of the period length. The constant Interest Rate applied to the account per period. Repeat data from a single period or group of periods through the timescale of the D-List. Performs seasonal adjustment of time. Performs seasonal adjustment of time. Provides the building blocks to simulate seasonal data using a variety of characteristics. Works out the level of supply needed to meet target forecasts for stock cover. Allows you to input stock cover and work out what purchases were needed to meet the target stock levels. Lets you use batch quantities in Stockflow calculations. Calculates a different percentage for each tier. Tiers are entered as a percentage and a bandwidth. Time returns the information requested by the option you have input. Allows you to accumulate an expense in your P&L over a specified number of periods in advance or arrears. Returns the maximum value of a specified list of items. Returns the minimum value of a specified list of items. Build equations using angles and trigonometry functions. Calculates the values for a specified input item using one or more rounding methods. Year-to-date calculation.

Proportion (p. 517)

Rate (p. 518) Repeat (p. 529)

SeasonLite (p. 529) SeasonPro (p. 533) Simul (p. 568)

StockFlow (p. 571)

StockFlowAF (p. 577)

StockFlowBQ (p. 582) Tier (p. 585)

Time (p. 586)

TimeSum (p. 593)

TMax (p. 601) TMin (p. 602) Transform (p. 603) TRound (p. 605)

YTD (p. 607)

User Guide 323

Chapter 12: Built in Functions (BiFs)

@Cumul
Cumulated=@Cumul(Original) Input/Output
Original Cumulated Input BiF Result

Parameter
D-List Item D-List Item

Description
Item you want to accumulate (Profit) Cumulative Total (Cumulative Profit)

How @Cumul works

Cumul calculates the cumulative totals in one row based on the original numbers in another row. For example, the BiF, Cumulative Profit=@Cumul(Profit), calculates a cumulative profit. In a timescale of generic months starting in April Cumulative Profit, Jun = (Profit,Apr)+(Profit,May) +(Profit,Jun).

Formula for Cumul

where n is the current period number.

Steps to use this BiF

1. Create a calculation D-List. 2. Click the Calculation cell of the item to which you want to apply the BiF. 3. Click Change item attributes. 4. Click BiF. 5. Select Cumul from the Function Name list. 6. Click Next. 7. Double-click the original item you want to cumulate in the Items box (in this case, Profit). 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Cycles
The @Cycles built in function combines sine and cosine waves. It has one input variable which must be a D-List item, one result variable, and no other output variables.

324 Analyst

Chapter 12: Built in Functions (BiFs) It can provide input for the @SeasonPro {Cycle%} input variable, and calculate seasonal factors from known Fourier form coefficients. The result is the sum of all the cycles of individual sine or cosine waves. Cycle = @Cycles(specs) Where the first four values of specs specify the first cycle, values 5 - 8 the next cycle, and so on to the last cycle, which is identified by setting the amplitude of the next potential cycle to zero. The specs are entered on one line in the D-Cube across the timescale as: Period 1 - Amplitude Cycle 1 Period 2 - Length Cycle 1 Period 3 - Start Date Cycle 1 Period 4 - 0=Sine, 1=Cosine for Cycle 1 Period 5 - Amplitude Cycle 2, and so on

Equations
The four input values for each cycle are {amplitude}, {length}, {start date} and {function}. The number of cycles is determined by stopping just before the first cycle that would have had zero amplitude. {amplitude} represents the height of the cycle. {length} represents the length in years over which the cycle repeats itself. {start date} represents the time in years at which the cycle starts. {function} is zero for a sine wave and 1 for a cosine wave.

The result is the sum of all the cycles. When {length} is zero, the cycle assumes the constant value {amplitude} everywhere. Other values of {function} are reserved for future use. Zero is the default value. When {function} = 0, the equation is: {Cycle} = {amplitude} * Sin(360 * ({time} - {start date}) / {length}) When {function} = 1, the equation is: {Cycle} = {amplitude} * Cos(360 * ({time} - {start date}) / {length}) where {time} is the center of the period measured in years, as returned by method 17 of the BiF Time.

Examples
A single sine wave, amplitude 100, length 1 year, starts at beginning of 2003: Cycle = cycles(100 1 2003 0 0). This is {Case 1} in the {monthly examples} cube in the sample data.

User Guide 325

Chapter 12: Built in Functions (BiFs)

The first two harmonics of a fourier form representing seasonal factors where cycles = Cycles (50 1 2003.083 1, -20 1 2003.083 0, 30 0.5 2003.083 1, -10 0.5 2003.083 0, 0). This is {Case 2} in cube {monthly examples}.

These three examples are {Case 1}, {Case 2} and {Case 3} in the cube {annual examples}. Each of them has a constant of 2000 as one of the cycles. {Case 1} Is a sine wave starting in 2000 with length = 20 years and amplitude = 200, {Case 2} Is a sine wave starting in 2003 with length = 6.5 years and amplitude = 300, {Case 3} is a combination of the waves in cases 1 and 2. The values of {specs} for each case are: {Case 1}: 200 20 2000 0 2000 0 0 0 0 ... {Case 2}: 300 6.5 2003 0 2000 0 0 0 0 ... {Case 3}: 200 20 2000 0 300 6.5 2003 0 2000 0 0 0 0 ...

326 Analyst

Chapter 12: Built in Functions (BiFs)

@Days
Days=@Days( ) Input/Output
Days BiF Result

Parameter
D-List Item

Description
Displays the days in the current period

How Days works

The Days BiF returns the number of days in each period by referring to the dates defined in the timescale D-List. This is defined by selecting Options from the D-List menu, and then selecting the Use as timescale check box. Next enter the From and To dates for each period. If the timescale is generic months, then @Days returns 30.42 (365/12) in each period

Formula for Days

Days = Number of days in period

Steps to use this BiF

1. Create a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Select the Calculation cell of the item where you want to display the number of days in the period. 4. Click Change item attributes. 5. Click BiF. 6. Select Days from the Function Name list. 7. Click Next. User Guide 327

Chapter 12: Built in Functions (BiFs) 8. No input is needed for this simple BiF so click Finish. 9. Click Apply. 10. Save the D-List.

@DaysOutstanding
Cash Payments = (Prime; Opening; Invoice; Closing; Level; Indicator; Days in Period; Cash Payments)
The @DaysOutstanding BiF is similar to the @DelayDebt BiF. However, the @DaysOutstanding BiF allows you to set the period length directly in the D-Cube by using the parameter Days in Period. The @DaysOutstanding BiF has the following parameters.

Input/Output
Prime Input

Parameter
D-List Item or Constant D-List Item

Description
Debtor or creditor balance at start of first period (default = 0) Debtor or creditor balance at start of subsequent periods, fed from the closing balance of the previous period The invoice amount to be paid Closing debtor or creditor balance, calculated from days outstanding Number of days outstanding or periods outstanding (default = 0) 0 = (default) assumes all periods have a length of 1 1 = days in period 2 = days in timescale

Opening

Output

Invoice Closing

Input Output

D-List Item D-List Item

Level

Input

D-List Item or Constant 0, 1, or 2

Indicator

Input

Days in Period Cash Payments

Input

D-List Item or Constant D-List Item

The length of the period in days. This is used only if Indicator = 1. Cash receipts or payments

BiF Result

328 Analyst

Chapter 12: Built in Functions (BiFs)

How @DaysOutstanding Works

The @DaysOutstanding BiF calculates cash receipts or payments based on the level of days outstanding. The inputs are Prime, Amount, Level, Indicator, and the Days in Period. The outputs are Opening and Closing. The BiF result is calculated in Cash Receipts. The closing debtor or creditor balance for each period is calculated by looking at invoice amounts for a specified number of days or periods. The days are taken first from the current period, then the previous periods. The level of days or periods outstanding can be any non negative number or fraction. When Indicator = 0, the Level is the number of periods. When Indicator = 1, the Level is the number of days taken from the Days in Period row. When Indicator = 2, the Level is the number of days taken from the start and end dates defined in the timescale D-List. In the example below, the debtor days for July are set at 41 days. The BiF Result is set up in the Cash Receipts row.

Apr
Prime Opening Sales Closing Level (days) 3000 3000 3000 4100 41

May

Jun

Jul

Aug

Sep

4100 3000 4000 41 3100

4000 3000 4065 41 2935

4065 3000 4000 41 3065

4000 3000 3968 41 3032

3968 3000 4065 41 2903

Cash Receipts 1900

Debtor days set to 41. All of July sales and 10 days worth of June sales gives Closing July = 4000 Cash Receipts = @DaysOutstanding (Prime; Opening; Invoices; Closing; Level; 2) Cash Receipts, Jul = (Sales, Jul) + (Opening, Jul) - (Closing, Jul) = 3000 + 4065 - 4000 = 3065 Closing, Jul = 31 days worth of July sales + 10 days worth of June sales = (31 / 31 * 3000) + (10 / 30 * 3000) = 3000 + 1000 User Guide 329

Chapter 12: Built in Functions (BiFs) = 4000 Opening, Jul = Closing, Jun For the first period only, the opening balance is taken from the parameter Prime. Opening Apr =Prime, Apr If the Level in any period requires days debtors be found from before the start of the timescale, then the first period will be replicated to provide sufficient days Negative Levels are treated as zero. Negative Days in Period are treated as zero. What happens when Days in Period = 0? If Days in Period is zero and Invoices of periods previous to the zero length period are by a future Level, the Invoices of the zero length period are added to the future period closing. If the first period has zero length and a future period has a level which means that there are not sufficient defined days in the timescale, then the first period invoices will be replicated once only because we do not know how many times to replicate them.

Formulas Used in @DaysOutstanding

The closing balance is calculated as a function of the level of days outstanding. Closing = (Days Outstanding / Days in Period) * Invoices this period - or (Closing, period n) = ([Level, period n] / [Days in period n]) * (Invoices, period n) However, if the level of days outstanding is greater than the days in the current period, the closing balance takes on the value of the invoice amounts for the current period plus a fraction of the previous period invoices. If the level of days outstanding goes back further, the closing balance is calculated as a function of current period invoices plus earlier period invoices.
If (Level, period n) > Days in period n Then (Closing, period n) = (Invoices, period n) + ([Invoices, period n - 1] * [Level - Days in period n] / Days period n - 1)

Cash payments are calculated to meet the closing balance levels required. Cash payments = Opening - Closing + Invoices

Opening balances are calculated as the closing balance from the previous period. For the first period only, the opening balance equals Prime. Opening, period n = Closing, period n - 1 Opening, period 1 = Prime, period 1

330 Analyst

Chapter 12: Built in Functions (BiFs)

Steps to Use this BiF

1. Open or create the D-Cube to apply the @DaysOutstanding to. The D-Cube must contain a calculation D-List and a timescale D-List. You should define the period length by entering it as a Days in Period item in the D-List, or the timescale D-List should have the From and To dates defined for each period. 2. Open the calculation D-List. 3. Click the Calculation cell to which you want to apply @DaysOutstanding. 4. Click Change item attributes. 5. Click BiF. 6. Select @DaysOutstanding. 7. Click Next. 8. Select the parameters by double-clicking an item. 9. Click Finish. 10. Click Apply. 11. Save the D-List.

@DCF
Constant=@DCF(Current;Rate;APR?;SwitchOver) Input/Output
Current Rate Input Input

Parameter
D-List Item D-List Item or Constant Leave Blank R P PR

Description
The base value The discount rate (inflation rate)

APR

Input

= annual % by default = annual rate (rate=%/100) = Periodic % = Periodic rate The switchover date defines the last historic period

Switchover

Input

None 19970501

= Treat all periods as historic = May 1, 1997 User Guide 331

Chapter 12: Built in Functions (BiFs)

Input/Output

Parameter
DList Today 5

Description
= Use rate defined in timescale D-List = Use today's date = Use May in monthly generic timescale D-List The result restated in a constant value

Constant

BiF Result

D-List item

How DCF Works

DCF stands for Discounted Cash Flow. DCF converts a future stream of cash flow to constant prices. It calculates the inflated value of todays money after one year. In simpler terms, it answers the question, "If I receive 1000 in a years time, what will that be worth in todays money after taking inflation into account?".

APR = Blank
For example: Constant Dollars = @DCF({Current Cost};Rate; ;19991231) uses an entered annual percentage rate of 10% and uses the switchover date of Dec 31st 1999. The period containing the switchover date is defined as the last historic period. In this example 1999 is the last historic period, 2000 onwards are future periods.

1999
Current Cost Rate Constant 1000 10% 1000

2000
1000 10% 909

2001
1000 10% 826

2002
1000 10% 751

2003
1000 10% 683

2004
1000 10% 621

For example, a cashflow of 1000 will only be worth 909 in a years time based on a discount rate of 10%:
Constant = 1000 (1 + 0.1) 2 = 909

A cashflow of 1000 in two years time will only be worth 826 when restated in todays money using a discount rate of 10%:
Constant = 1000 (1 + 0.1) 2 = 826

332 Analyst

Chapter 12: Built in Functions (BiFs) The examples that follow illustrate the different ways the discount rate and the switchover date parameters are entered.

APR = R
Example: Constant Dollars = @DCF({Current Cost};Rate;R;Dlist) uses an entered annual rate of 0.1 (equivalent to 10%) and takes the switchover date from the timescale D-List. In this example the switchover date has been set to Dec 31st 1999.

1999
Current Cost Rate Constant Dollars 1000 0.100 1000

2000
1000 0.100 909

2001
1000 0.100 826

2002
1000 0.100 751

2003
1000 0.100 683

2004
1000 0.100 621

Rate = 10 (Constant), APR = Blank

Example: Constant Dollars = @DCF({Current Cost};10; ;19991231) uses a constant annual percentage rate of 10% and takes the switchover date as Dec 31st 1999.

1999
Current Cost 1000 Rate Constant 10% 1000

2000
1000 10% 909

2001
1000 10% 826

2002
1000 10% 751

2003
1000 10% 683

2004
1000 10% 621

APR = P Switchover = 4 ,
Example: Constant Dollars = @DCF({Current Cost};Rate;P;4) uses an entered periodic percentage rate of 0.797% and uses the switchover date of April. Note that the period number can only be used for a generic monthly timescale D-List.

Jan
Current Cost Rate Constant 1000 0.797% 1024

Feb
1000 0.797% 1016

Mar
1000 0.797% 1008

Apr
1000 0.797% 1000

May
1000 0.797% 992

Jun
1000 0.797% 984

User Guide 333

Chapter 12: Built in Functions (BiFs)

APR = Blank, Switchover = 4

Example: Constant Dollars = @DCF({Current Cost};Rate; ;4) uses an entered annual percentage rate of 10% and uses the switchover date of April. Note that the period number can only be used for a generic monthly timescale D-List.

Jan
Current Cost Rate Constant 1000 10% 1024

Feb
1000 10% 1016

Mar
1000 10% 1008

Apr
1000 10% 1000

May
1000 10% 992

Jun
1000 10% 984

Other valid examples are as follows: Constant Dollars = @DCF({Current Cost};4.5; ;Dlist) uses an annual percentage rate of 4.5% and uses the switchover date from the timescale D-List. Constant Dollars = @DCF({Current Cost};Rate;P;Today) uses a periodic percentage rate and todays date as switchover. Constant Dollars = @DCF({Current Cost};Rate;PR;5) uses a periodic rate and uses May, the fifth period in a monthly timescale D-List, as the switchover date.

Formulas used by DCF

Constant = Current (1 + r) n

Where: r = discount rate expressed as a decimal fraction n = number of periods into the future There are four acceptable methods of entering the discount rate: An annual percentage, an annual rate, a periodic percentage, and a periodic rate. The annual equivalent column below shows that the periodic monthly rate 0.00797 (0.797% per month) is equivalent to an annual rate of 10%.

Parameter
Leave blank R P

Meaning
= annual % = annual rate = periodic %

Annual Equivalent Relationship

10 0.1 0.797 % (default) R=%/100 P = PR*100

334 Analyst

Chapter 12: Built in Functions (BiFs)

Parameter
PR

Meaning
= periodic rate

Annual Equivalent Relationship

0.00797 (1+PR)12 = (1 + R) for 12 periods

Steps to Use this BiF

1. Create a calculation D-List. Refer to the tables above for D-List item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Constant Dollars. 3. Click Change item attributes. 4. Click BiF. 5. Select DCF from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Specify APR: In the APR box, you have several options. Leave blank to default to an annual percentage Type P for periodic percentage Type PR for periodic rate Type R for annual rate

Specify Use Switchover: In the Use Switchover box, you have several options: Type None to treat all periods as historic. Type Dlist to use the switchover date defined in the timescale D-List Type Today to use todays date Type a date (for example, 19990609) to specify a date Type a number (for example, 5) to specify a generic month

Switchover parameters entered in the BiF formula will override the switchover date contained in the timescale D-List.

1999
Current Cost Rate Constant 1000 10% 1000

2000
1000 10% 909

2001
1000 10% 826

2002
1000 10% 751

2003
1000 10% 683

2004
1000 10% 621 User Guide 335

Chapter 12: Built in Functions (BiFs) 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Decum
Original=@Decum(Cumulated) Input/Output
Cumulative Input

Parameter
D-List Item

Description
Item you want to break down (Cumulative Sales) Original item (Sales)

Original

BiF Result

D-List Item

How Decum Works

Starting from the cumulated totals, Decum calculates the original series. For example Sales=@Decum({Cumulative Sales}) breaks down cumulative sales into monthly sales. Sales, Jun = (Cumulative Sales,Jun) - (Cumulative Sales, May)

Formula for Decum

(Original, Period n) = (Cumulative, Period n) - (Cumulative, Period n-1)

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Sales. 3. Click Change item attributes. 4. Click BiF. 5. Select Decum from the Function Name list. 6. Click Next. 7. Double-click the original item you wish to cumulate in the Items box - in this case, Cumulative Sales. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

336 Analyst

Chapter 12: Built in Functions (BiFs)

@Delay
Delayed=@Delay(Prime;Opening;Inputs;Closing;% Period(s)) Input/Output Parameter
Prime Input

Description

D-List Item or Balance at start of first period (default=0) Constant D-List Item Balance at start of subsequent periods, fed from closing of last period Closing balance calculated Invoices Percentage of current period's invoices paid in current period, next period, and so on (default=0) . The BiF wizard accepts 5 period of input; if more are required these can be manually entered into the formula by editing the calculation. Cash receipts or payments

Opening

Output

Closing Inputs %period1 to n

Output Input Input

D-List Item D-List Item D-List Item

Delayed

BiF Result

D-List Item

How Delay Works

Delay calculates receivables or payables based on a delay between the time of invoice and the time of payment. For invoices in a given month, a certain percentage is paid by the end of the month, a certain percentage paid the next month, and so on. This is represented by the inputs % Period1, % Period2, % Period3, and so on up to the greatest delay expected. The sum of these percentages must equal 100% to ensure that all invoices are paid. At the beginning of the fiscal year the opening receivable or payable balances are entered in the item, Prime, in the BiF Function Wizard. The invoices incurred in each period are entered in one row, the resulting cash receipts (or receivables) calculated as an output in another row. The @Delay function calculates the cash received (paid) in a given period based on the sales (purchases) history. The variable, Prime, represents the opening balance in period 1, whereas the variable Opening represents the opening balance in periods 1 to period n. The opening balance is calculated as being equal to the closing balance from the previous period. In the example shown, the BiF result is calculated in the Cash paid row.

Jan
Prior Year Balance 1000

Feb
0

Mar
0

Apr
0

May
0

Jun
0

User Guide 337

Chapter 12: Built in Functions (BiFs)

Jan
Opening Balance Invoices % This Period % Next Period % Period +3 % Period +4 Cash Paid Closing Balance Where: Cash paid = 1000 500 40% 25% 20% 15% 600 900

Feb
900 500 40% 25% 20% 15% 575 825

Mar
825 500 40% 25% 20% 15% 625 700

Apr
700 500 40% 25% 20% 15% 650 550

May
550 500 40% 25% 20% 15% 500 550

Jun
550 500 40% 25% 20% 15% 500 550

@Delay({Year-end};Opening;Invoices;Closing;{%thisperiod}; {%nextperiod};{%period+3};{%period+4}) +((Opening, Jan)+(Invoices, Jan))*(%period+3,Jan)/100 +((Invoices, Feb)*(%next period, Feb)/100) +((Invoices, Mar)*(%this period, Mar)/100)

Cash paid, Mar

+(1000+500)*(20/100) +(500*(25/100) +(500*40/100)

= Opening, Apr = =

625 Closing,Mar 700

The item, Cash paid, is a function of Year End Balance, Invoice, % This Period, %Next Period, % Period+3, and %Period+4. The exact mathematical formula it uses is not visible within the D-List, but is listed below.

338 Analyst

Chapter 12: Built in Functions (BiFs)

Formulas for Delay

Cash Paid, this month = +(Input current month) * (%period1 current month)/100 +(Input last month) * (%period2 from last month)/100 +(Input 2 months ago) * (%period3 from 2 months ago)/100 +(Input 3 months ago) * (%period4 from 3 months ago)/100 + ........ (Opening n months ago) * (%period n+1 from n months ago/100) The opening balance from the prior year is assigned to the future month using the percentages entered in the first time period. Closing Opening, period 1 Opening, this month = = = Opening + Inputs - Cash Paid Prime, period1 Closing, last month

Note: The parameters do not necessarily have to be D-List items; they can be also be constants.

Example
@Delay(0;Opening;Invoices;%this;%next;%plus2;%plus3) will have an opening balance of zero.

Example
@Delay(1000;Opening;Invoices;%this;%next;%plus2;%plus3) will have an opening balance of 1000.

Steps to Use this BiF

1. Create a calculation D-List containing the required lines and parameters. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Cash Paid. 3. Click Change item attributes. 4. Click BiF. 5. Select Delay from the Function Name list. 6. Click Next. 7. Double-click the parameters from the function wizard. Note: The parameter, Prime, can either be typed in as a constant or can refer to a D-List item.

User Guide 339

Chapter 12: Built in Functions (BiFs) 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@DelayDebt
Receipts=@DelayDebt(Prime;Opening;Sales;Closing;Level;Indicator) Input/Output
Prime Input

Parameter
D-List Item or Constant D-List Item

Description
Debtor balance at start of first period (default=0) Debtor balance at start of subsequent periods, fed from closing balance of the previous period Actual sales Closing debtor balance, calculated from debtor days Number of debtor days or periods (default=0) 0=no. of periods (default) 1=no. of days

Opening

Output

Sales Closing

Input Output

D-List Item D-List Item

Level

Input

D-List Item or Constant 1 or 0

Indicator

Input

Receipts

BiF Result

D-List Item

Cash receipts required to meet debtor targets

How DelayDebt works

DelayDebt calculates cash receipts based on debtor days by referring to recent sales history. The same calculation may also be used to work out cash payments based on creditor days. The inputs are Prime, Sales, Level and Indicator. The outputs are Opening and Closing. The BiF result is calculated in Cash Receipts. The closing debtor balance for each period is calculated by referring to historic sales levels for a specified number of days or periods. The days are taken first from the current period then the previous periods. The level of debtor days or periods may be any positive number and may have a fractional part.

340 Analyst

Chapter 12: Built in Functions (BiFs) When Indicator = 0 the level is the number of periods. When Indicator = 1 the level is the number of days. For the BiF to use the number of days, the start and end dates must be defined for each period in the timescale D-List. In the example shown, the debtor days for July are set at 41 days. The BiF result is set up in the Cash Receipts row.

Apr
Prime Opening Sales Closing Level (days) Cash Receipts Where: Cash Receipts Cash Receipts, Jul 3000 3000 3000 4100 41 1900

May

Jun

Jul

Aug

Sep

4100 3000 4000 41 3100

4000 3000 4065 41 2935

4065 3000 4000 41 3065

4000 3000 3968 41 3032

3968 3000 4065 41 2903

=@DelayDebt(Prime;Opening;Sales;Closing;Level;1) =(Sales, Jul) + (Opening, Jul) - (Closing, Jul) =3000 + 4065 - 4000 =3065

Closing, Jul

=31 days of July sales + 10 days worth of June sales =(31/31 * 3000) + (10/30 * 3000) =3000 + 1000 =4000

Opening, Jul

Closing, Jun

For the first period only, the opening balance is taken from the parameter, Prime. Opening, Apr= Prime, Apr

Formulas for DelayDebt

The closing balance is calculated as a function of the level of debtor days. Closing = (Debtor Days/ Days in Period) * Sales this period -- or --

User Guide 341

Chapter 12: Built in Functions (BiFs) (Closing, period n) = ((Level, period n)/ (Days in period n)) * (Sales, period n) However, if the level of debtor days is greater than the days in the current period, the closing balance assumes the value of the sales for the current period plus a fraction of the previous period sales. If the level of debtor days regresses further still, the closing balance is calculated as a function of current period sales plus earlier period sales. If (Level, period n) > Days in period n Then (Closing, period n) = (Sales, period n) + ((Sales, period n-1) *(Level - Days in period n) / Days Period n-1 )) Cash receipts are calculated to meet the closing debtor levels required: Cash receipts = Opening - Closing + Sales Opening debtors are calculated as the closing debtor balance from the previous period. For the first period only, the opening balance equals Prime. Opening, Period n = Closing, Period n-1 Opening, Period 1 = Prime, Period 1

Steps to Use this BiF

1. Create a calculation D-List. DelayDebt requires a timescale D-List with from and to dates defined for each period or it will use an average of 365/12=30.42 days per month.

Item Name
Prime Opening Sales Closing Level Cash Receipts

Calculation

Output

Output

BiF

2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Cash Receipts. 3. Click Change item attributes. 4. Click BiF. 5. Select DelayDebt from the Function Name list. 6. Click Next.

342 Analyst

Chapter 12: Built in Functions (BiFs) 7. Double-click the parameters in the BiF Function Wizard. Note: The parameters, Prime and Level, can either be typed in as constants or can refer to D-List items. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@DelayStock
Purchases=@DelayStock(Prime;Opening;Demand;Closing;Level;Indicator) Input/Output
Prime Input

Parameter
D-List Item or Constant D-List Item

Description
Stock balance at start of first period (default = 0) Stock balance at start of subsequential periods Sales demand expected Closing stock balance Number of stock days or periods

Opening

Output

Demand Closing Level

Input Output Input

D-List Item D-List Item D-List Item or Constant 1 or 0

Indicator

Input

0 = no. periods (default) 1 = no. of days

Purchases

BiF

D-List Item

Purchases required to meet stock targets

How DelayStock works

DelayStock calculates purchases required to meet future demand. The closing stock for each period is calculated by looking ahead at sales demand for a specified level of days or periods. Purchases are calculated to meet the closing stock levels required. The inputs are: Prime, Demand, Level, and Indicator. The outputs are: Opening and Closing. The BiF result is calculated in the Purchases row.

User Guide 343

Chapter 12: Built in Functions (BiFs) When Indicator = 0 the level is the number of periods. When Indicator = 1 the level is the number of days. Opening stock is calculated as the closing stock from the previous period, except for the first period, which is set to the variable, Prime. Level may be any positive number and may have a fractional part. For the last few periods the demand in the last period is replicated to provide any missing future periods required by the level of stockturn days. The maximum value allowed for Level is the number of time periods (or the total number of days) in the time D-List. If this is exceeded, a message is displayed and the maximum is used: For example, the total number of time periods, or days, in the timescale D-List is used.

Example
Purchases = @DelayStock(1000; Opening; Sales; Closing; Level; 1) uses an opening balance of 1000 and stock-turn days to determine closing stock levels.

Apr
Stock Prior Year Opening Stock Sales Closing Stock Level (days) Purchases 5000 5000 2000 6000 61 3000

May

Jun

Jul

Aug

Sep

6000 3000 6000 61 3000

6000 3000 6000 62 3000

6000 3000 6000 61 3000

6000 3000 6000 61 3000

6000 3000 6000 61 3000

The formula used is best illustrated by an example. Suppose the stock level is set to 62 days for June: Closing, Jun = 31 days worth of July Sales + 31 days worth of August Sales = 3000 + 3000 = 6000 Purchases = Sales + Closing - Opening = 3000 + 6000 - 6000 = 3000

Example
Purchases = @DelayStock(0; Opening; Sales; Closing; Level; 0) uses an opening balance of zero and stock-turn periods rather than days.

344 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Stock Prior Year Opening Stock Sales Closing Stock Level (days) Purchases 0 0 1000 4000 3.0 5000

Feb

Mar

Apr

May

Jun

4000 1000 6000 3.0 3000

6000 1000 8000 3.0 3000

8000 2000 7500 2.5 1500

7500 3000 7500 2.5 3000

7500 3000 7500 2.5 3000

Example
Purchases = @DelayStock(Prime; Opening; Sales; Closing; Level; 0) uses an opening balance taken from Prime in January and stock-turn periods to determine closing stock levels.

Jan
Stock Prior Year Opening Stock Sales Closing Stock Level (days) Purchases 2000 2000 1000 4000 3.0 3000

Feb

Mar

Apr

May

Jun

4000 1000 6000 3.0 3000

6000 1000 8000 3.0 3000

8000 2000 7500 2.5 1500

7500 3000 7500 2.5 3000

7500 3000 7500 2.5 3000

Formulas for DelayStock

The closing balance is calculated as a function of the level of stockturn days. Closing Stock = (Stockturn Days/ Days Next Period) * Sales Next Period -- or -(Closing, Period n) = ((Level, Period n)/ (Days in Period n+1) ) * (Sales, Period n+1) However, if the level of stockturn days is greater than the days in the next period, the closing balance assumes the value of the sales for the next period plus a fraction of the following periods sales. If that still is not enough, the formula looks ahead to the subsequent periods. For the last few periods, the demand in the last period is replicated to provide any missing future periods required by the level of stockturn days.

User Guide 345

Chapter 12: Built in Functions (BiFs) If (Level, Period n) > Days in Period n+1 Then (Closing, Period n) = (Sales, Period n+1) + ((Level, Period n) - Days in Period n+1) / (Days in Period n+2) * (Sales, Period n+2) Purchases are calculated to meet the closing stock levels required: Purchases = Closing - Opening + Sales Opening stock balances are calculated as the closing stock balance from the previous period except for the first period only when the opening balance equals Prime. Opening, Period n = Closing, Period n-1 Opening, Period 1= Prime, Period 1

Steps to use this BiF

1. Create a calculation D-List. DelayStock requires a timescale D-List with from and to dates defined for each period or it will use an average of 365/12=30.42 days per month. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Purchases. 3. Click Change item attributes. 4. Click BiF. 5. Select DelayStock from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: The parameters, Prime and Level, can either be typed in as constants or can refer to D-List items. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@DepnAnnual
Depreciation=@DepnAnnual(Capitalization;Life;Days;Method) Function
Capitalization Input

Parameter
D-List Item

Description
Asset capitalization, usually the cost of purchase The life of the capitalized assets in years

Life

Input

D-List Item or Constant

346 Analyst

Chapter 12: Built in Functions (BiFs)

Function
Days Method Input Input

Parameter
D-List Item D-List Item

Description
The number of days in each time period The depreciation method to use. Select from the following: 1 = Straight line 2 = Sum of year digits 3 = Diminishing balance

Depreciation

Result

The depreciation charge for P&L

How DepnAnnual works

The @DepnAnnual BiF combines the functionality of existing BiFs (@DepnSLD, @DepnSYD, and @DepnDB). This BiF allows you to have time periods of variable length in a timescale D-List (for example, you can have mix monthly periods, quarters, and entire years) and to apply different depreciation methods to different items in a D-List. For example, you can apply a straight line method to one asset and a depreciating balance method to another asset. The method is input once into the first period of the timescale for each asset / item. Using the @DepnSLD, @DepnSYD, and @DepnDB BiFs, you must assume that all periods in the time dimension were equal therefore mixed-interval time dimensions could not be used. Also, using these BiFs, you cannot apply different methods to the same list of items within one BiF calculation line. The capitalization is treated as a stream of assets being acquired. Depreciation is accumulated for the asset value in each successive time period, producing a stream of depreciations corresponding to the sum of all the input assets. If the life of any asset extends beyond the time profile you have selected, the residual values are ignored. No salvage value is allowed as an input. Any period length is allowed for @DepnAnnual. You can have a mixture of months, quarters, years, or longer in the timescale. The periods must be in chronological order and consecutive. If you enter days as a negative number, the period length is treated as zero. If you choose straight line or sum of the year digits as the depreciation method, life is the time, in years, over which the asset is depreciated to a zero value. Generally, this is a positive integer. If you enter days as a negative integer, the period length is treated as zero. For declining balance method (3) the life as entered as a percentage per annum. In the unlikely event that a negative life is used, the minus sign is ignored. So, for example, life = -10 or +10 both calculate depreciation of 10% per annum.

Example using straight line method

The example below shows depreciation calculated on an annual basis based on the straight line method (1). For each year (a year being fixed at 365 days), depreciation is allocated to time periods according to the number of days in each period.

User Guide 347

Chapter 12: Built in Functions (BiFs) For example, in Q4, depreciation = (100000/4)*92/365 = 6301 DepnAnnual=@DepnAnnual(Capitalization;Life;Days;Method)

Q1
Capitalization Life Days Depreciation 100000 4 91 6233

Q2
0

Q3
0

Q4
0

Year 1
100000

Year 2
0

Year 3
0

Year 4
0

91 6233

91 6233

92 6301

365 25000

365 25000

365 25000

365 25000

Example using sum of year digits method

In the sum of year digits method (2) depreciation is expressed as a fraction with the denominator being the sum of the years digits. The annual depreciation starts high, then gets less as the years go by. For example, in year 1, depreciation = (100000 * 4/(4+3+2+1)) = 40000 The Q4 depreciation is based on the number of days in the quarter = 40000 *92/365 = 10082 In year two, depreciation = (100000 * 3/(4+3+2+1)) = 30000 In year three, depreciation = (100000 * 2/(4+3+2+1)) = 20000 In year four, depreciation = (100000 * 1/(4+3+2+1)) = 10000

Q1
Capitalization Life Days Depreciation 100000 4 91 9.973

Q2
0

Q3
0

Q4
0

Year 1
100000

Year 2
0

Year 3
0

Year 4
0

91 9973

91 9973

92 10082

365 40000

365 30000

365 20000

365 10000

Example using diminishing balance method

If you choose the diminishing balance depreciation method, life is the annual rate of deprecation. 10 would denote 10%, not 10 years. This should be a positive number less than 100 (100% denotes an asset that is fully depreciated). For all methods, if life is 0, there is no depreciation. In the diminishing balance method (3), an annual percentage is entered instead of the life. For example, in year one, the depreciation is 10% of the opening balance = 100000 * 10/100 = 10000 In Q4 depreciation = 10000 *92/365 = 2521 348 Analyst

Chapter 12: Built in Functions (BiFs) In year two, the opening balance has been reduced to 90000, by taking off the depreciation from the previous year. The depreciation in year two is 10% of this smaller opening balance = 90000 *10/100 = 9000

Q1
Capitalization 100000 Rate Days Depreciation 10 91 2493

Q2
0

Q3
0

Q4
0

Year 1
100000

Year 2
0

Year 3
0

Year 4
0

91 2493

91 2493

92 2521

365 10000

365 9000

365 8100

365 7290

The days are the notational length of the time period, in days. A year is considered to be 365 days long, so you should use the following days: for months, days=30.4166...=365/12. You must specify it to sufficient accuracy. for quarters, days=91.25=365/4 for years, days=365, and so on

Method is used to apply different methods to different types of assets. Usually, a single stream of assets will use the same method, but deciding which method is up to you. The method that applies in the period of acquisition is the one that is used. The default mode is method 1 (straight line). The following example shows a single asset (life=1 year) capitalized in the first month only. Note that the days are calculated by the formula: days=365/12

Jan
Capn 120 Life Days 1 30.4

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

Jan
0

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 10

30.4 0

Depn 10

The following example shows a series of assets depreciated over one year.

Jan
Capn 120 Life 1

Feb
0

Mar Apr
0 120 1

May Jun
0 0

Jul
120 1

Aug Sep
0 0

Oct
0

Nov Dec
60 1 0

Jan
0

User Guide 349

Chapter 12: Built in Functions (BiFs)

Jan
Days 30.4 Depn 10

Feb
30.4 10

Mar Apr
30.4 10 30.4 20

May Jun
30.4 20 30.4 20

Jul
30.4 30

Aug Sep
30.4 30 30.4 30

Oct
30.4 30

Nov Dec
30.4 35 30.4 35

Jan
30.4 25

The following example shows a different depreciation life for each asset.

Jan
Cap'n 120 Life 2

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
120 1

Aug Sep
0 0

Oct
0

Nov Dec
0 0

Jan
0

Days 30.4 Dep'n 5

30.4 5

30.4 5

30.4 5

30.4 5

30.4 5

30.4 15

30.4 15

30.4 15

30.4 15

30.4 15

30.4 15

30.4 15

The following example shows that if life never varies (for example, it is always 4), for convenience you can put the same value in every cell of life, even beneath zero assets.

Jan
Capn 480 Life Days 4 30.4

Feb
0 4 30.4 10

Mar Apr
0 4 30.4 10 0 4 30.4 10

May Jun
0 4 30.4 10 0 4 30.4 10

Jul
960 4 30.4 30

Aug Sep
0 4 30.4 30 0 4 30.4 30

Oct
0 4 30.4 30

Nov Dec
0 4 30.4 30 0 4 30.4 30

Jan
0 4 30.4 30

Depn 10

The following example shows a timescale with periods of varying length: y1=1q1+2q1+3q1+4q1 {periods in year} has time average totals days=365/{periods in year} depn-1=@DepnAnnual(one;4;days;1)=straight line over 4 years depn-2=@DepnAnnual(two;6;days;2)=sum of the year digits over 6 years depn-3=@DepnAnnual(three;7;days;3)=diminishing balance of 7 percent

350 Analyst

Chapter 12: Built in Functions (BiFs)

Q1

Q2

Q3

Q4

Year 1 Year 2 Year 3 Year 4 Year 5 Year 6

365 0 365 0 365 0 365 0 365 0 0

Days

91.25 91.25 91.25 91.25 365 1,000 0 0 1,000

Capn 0 Depn 0 1 Depn 0 2 Depn 0 3

62.50 62.50 62.50 187.50 250.00 250.00 250.00 62.50

71.43 71.43 71.43 214.29 250.00 202.38 154.76 107.14 59.52

17.50 17.50 17.50 52.50

66.33

61.68

57.36

53.35

49.61

Additional Notes
Each asset starts depreciating at the beginning of the period it is acquired. For non-integer life, both straight-line and sum of year digits methods can tolerate a life that is not a whole number of years.

Example
If you enter a life of 2.5 years, it will start depreciating on the day it was entered in the Capitalization row, and stop 2.5 years later. If you use a non-integer life for the sum of year digits method, it will work out different depreciation rates for each block of 365 days (a step function), again starting on the day of capitalization. For instance - if you enter a life of 2.5, it will be 2.5/ (2.5+1.5+0.5)= 2.5/4.5 of the capital cost for the first 365 days, 1.5/4.5 for the next 365 days, and 0.5/4.5 for the remaining 183 days. Or, if the life were 0.5, then 0.5/0.5 of the capital cost would be depreciated in the first 183 days. A life of zero, or negative life, gives a depreciation result of zero. When you are showing several asset purchases in the same row, the depreciation of each is worked out separately, and each asset only starts to depreciate in the time period where it was entered in the capitalization row. The overall depreciation shown is then the sum of each individual asset depreciation. For more information, see DepnDB (p. 352), DepnSLN (p. 355), and DepnSYD (p. 356). DepnSLN and DepnSYD give the same result as DepnAnnual, provided that: DepnSLN and DepnSYD have an indicator of 1 All the periods are exactly the same length (not more than 365 days) Life is a whole integer number of years Because DepnDB diminishes the balance each period and DepnAnnual diminishes the balance each year, DepnDB gives the same result as DepnAnnual only when all the periods are years, each exactly 365 days long.

User Guide 351

Chapter 12: Built in Functions (BiFs)

Steps to Use this BiF

1. Create a calculation D-List. Refer to the tables above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Depreciation. 3. Click Change item attributes. 4. Click BiF. 5. Select DepnAnnual from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: The parameter Indicator should be typed in a constant. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@DepnDB
Depreciation=@DepnDB(Capitalization;%Rate;Period/Year indicator) Input/Output
Capitalization Input

Parameter
D-List Item

Description
Asset capitalization, usually the cost of purchase Percentage depreciation rate. Defaults to zero if blank; implies no depreciation. 0=%/period, 1=%/annum Diminishing balance depreciation result

%Rate

Input

D-List Item or Constant 1 or 0 D-List Item

Indicator Depreciation

Input BiF Result

How DepnDB works

DepnDB calculates depreciation based on diminishing balances. Depreciation for the first period is calculated by taking a percentage of the opening asset capitalization. Depreciation for the next period is calculated based on taking a percentage of the diminished balance. Thus the beginning depreciation is high but the charge progressively decreases, although the asset is never completely written off. Indicator is set to 0 for a periodic rate, 1 for an annual rate. If you set Indicator to 1 when using a monthly D-List, the program will convert the entered annual rate to a periodic rate.

352 Analyst

Chapter 12: Built in Functions (BiFs) The example below shows a depreciation calculation based on a declining balance of 10% per annum (period indicator =1). This only works for periods of equal lengths. If you have uneven period length, use @DepnAnnual instead. DepnDB=@DepnDB(Capitalization;{% Rate};1

Jan

Feb

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

Capn 100000 0 Rate 10 % 833. 3

Depn 833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

833. 3

The example below shows a declining balance based on 10% per period (period indicator =0) using time periods of equal length. DepnDB=@DepnDB(Capitalization;{% Rate};0)

Jan
Capn Rate Depn 100000 10% 10000

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

9000 8100 7290 6561 5905 5314 4783 4305 3874 3487 3138

The example below shows a depreciation calculation of 10% per annum using years of equal lengths (period indicator =1). DepnDB=@DepnDB(Capitalization;{% Rate};1)

2002
Capn Rate Depn 100000 10% 10000

2003
0

2004
0

2005
0

2006
0

2007
0

2008
0

2009
0

2010
0

9000

8100

7290

6561

5905

5314

4783

4305

Per Annum method

In @DepnDB, setting the period/year indicator to 1 means that the life is treated as a percentage per annum. The depreciation for the first 365 days is worked out as Capitalization * Life/100. Exactly 365 days after the capitalization was entered, a smaller daily depreciation rate is worked out as the current opening balance (capitalization less depreciation to date) multiplied by the life/

User Guide 353

Chapter 12: Built in Functions (BiFs) 100. Every 365 days thereafter, on the anniversary of the original capitalization, a new daily depreciation rate is worked out. This is a step function that puts more depreciation in the early years. In other words, the daily depreciation rate is higher in the first year than the later years, but is constant within each year. A year is a block of 365 days starting in the time period where you entered the capitalization. When you are showing several asset purchases in the same row, the depreciation of each is worked out separately, and each asset only starts to depreciate in the time period where it was entered in the capitalization row. The overall depreciation is calculated as the sum of each individual asset depreciation.

Period Lengths
@DepnDB requires periods to be of equal length. It will ignore the individual period lengths set in the timescale. Instead, a notional average period length is calculated as the total number of days in the timescale divided by the total number of periods. DepnDB uses this notional average period length to spread the depreciation calculated for each block of 365 days. The rule of thumb is that you should only use DepnDB (and Depn SLN, DepnSYD) when periods are of equal length.

Negative life
For declining balance method, the life as entered as a percentage per annum. In the unlikely event that a negative life is used, the minus sign is ignored. So, for example, life = -10 or +10 both calculate depreciation of 10% per annum.

Formula for DepnDB

Depreciation = (capitalization - accumulated depreciation to date) * (rate / 100)

Steps to Use this BiF

1. Create a calculation D-List. Refer to the tables above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Depreciation. 3. Click Change item attributes. 4. Click BiF. 5. Select DepnDB from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: The parameter Indicator should be typed in a constant. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

354 Analyst

Chapter 12: Built in Functions (BiFs)

@DepnSLN
Depreciation=@DepnSLN(Capitalization;Life;Period/Year indicator) Input/Output
Capitalization Input

Parameter
D-List Item

Description
Asset capitalization, usually the cost of purchase Life of the asset. If blank, it defaults to zero and does not depreciate 0=life in periods (default) 1=life in years

Life

Input

D-List Item or Constant 1 or 0

Indicator

Input

Depreciation

BiF Result

D-List Item

Straight line depreciation result

How DepnSLN works

DepnSLN calculates depreciation based on a straight line method. The depreciation is calculated by dividing the asset capitalization by the life. No salvage value is allowed as an input. Two inputs are required: Asset capitalization and the life in periods or years. The life can either be an item in the D-List or a constant to apply to all items for all periods. Zero life implies no depreciation at all. A fraction of a life is rounded up to the nearest whole time period. The indicator should be set to 0 for life in periods, 1 for life in years. Example: Depreciation=@DepnSLN(Capitalisation;Life;1) (Indicator = 1) takes the life in years, capitalization as inputs, and calculates the depreciation in each period.

Jan
Capn 2400 Life 10

Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Year
0 0 0 0 0 0 0 0 0 0 0 2400

Depn 20 Example:

20

20

20

20

20

20

20

20

20

20

20

240

Depreciation=@DepnSLN(Capitalization;Life;0) (Indicator = 0) takes the life in periods, capitalization as inputs, and calculates the depreciation in each period.

User Guide 355

Chapter 12: Built in Functions (BiFs)

Jan
Capn 2400 Life 10

Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Year
0 0 0 0 0 0 0 0 0 0 0 2400

Depn 240

240 240 240 240

240 240 240 240 240 0

2400

Formula used by DepnSLN

Up to the period where the life of the asset has expired: Depreciation = capitalization / life of the asset

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Depreciation. 3. Click Change item attributes. 4. Click BiF. 5. Select DepnSLN from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: The parameter Indicator should be typed in as a constant. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@DepnSYD
Depreciation=@DepnSYD(Capitalization;Life;Period/Year indicator) Input/Output Parameter
Capitalization Input D-List Item

Description
Asset capitalization, usually the cost of purchase Life of the asset. If blank, it defaults to zero and does not depreciate

Life

Input

D-List Item or Constant

356 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
Indicator Input 1 or 0

Description
0=life in periods (default) 1=life in years

Depreciation

BiF Result

D-List Item

Straight line depreciation result

How DepnSYD works

DepnSYD calculates the depreciation by dividing the capitalization by a weighting that decreases over time. No salvage value is allowed. Example: Depreciation=@DepnSYD(Capitalization; 5;1) This calculates the depreciation as 5/15 of the asset value in the first year, 4/15 of the value in the second year, 3/15 of the value in the third year and so on until it is fully depreciated. The denominator of 15 is the sum of the years digits 1+2+3+4+5=15. Depreciation, 2000 = (Capitalization) * Years life remaining / Sum of Years Digits = 15000 * 4 / 15 = 4000

1999
Capitalization Life Depreciation 15000 5 5000

2000

2001

2002

2003

2004

4000

3000

2000

1000

Per Annum method

DepnSYD tolerates periods >365 days and life that is set at a non-integer value. In @DepnSYD, setting the period/year indicator to 1 means that the life is treated as the number of years over which to depreciate each asset. The daily depreciation rate is worked out based on the sum of years digits. So if life=3, then the depreciation is 3/(3+2+1) =3/6 of the capitalization for the first 365 days, 2/ 6 for the next block of 365 days, and 1/6 for the final block of 365 days since the date of capitalization. This is a step function that puts more depreciation in the early years. The daily depreciation rate is higher in the first year than the later years, but is constant within each year. A year is a block of 365 days starting in the time period where you entered the capitalization. For example, if the life were 2 years, then depreciation in the first year would be 2(2+1) = 2/3 = 0. 666 of the capital expenditure. The depreciation in the next year is 1/3 = 0.333 * capital expenditure. Because the per annum method results in a step function, the monthly depreciation remains the same at 2/(3*12) = 0.0555 per month for the first 12 months, decreasing to 1/(3*12) =0.0277 per month for the next 12 months. User Guide 357

Chapter 12: Built in Functions (BiFs) When you are showing several asset purchases in the same row, the depreciation of each is worked out separately. Each asset only starts to depreciate in the time period where it was entered in the capitalization row. The overall depreciation is calculated as the sum of each individual asset depreciation.

Per period method

In @DepnSYD, leaving the period/year indicator at 0, means that the life is treated as the number of periods over which to depreciate each asset. The depreciation will go down every period, making it a smoother and steeper depreciation curve than the per annum method. For example, if the life were 24 periods, then depreciation in the first period = 24/(24+23+22+... +1) = 24/ 300 = 0.08 of the capital expenditure. In the next month, it would be 23/(24+23+22+ ... +1) =0.0766, and so on.

Period lengths
@DepnSYD requires periods to be of equal length. It will ignore the individual period lengths set in the timescale. Instead a notional average period length is calculated as the total number of days in the timescale divided by the total number of periods. The rule of thumb is that you should only use DepnSYD (and Depn SLN, DepnDB) when periods are of equal length.

Non-integer life
@DepnSYD can tolerate life that is a non-integer value. For example, if you enter a life of 2.5 years (using the per annum method =1), it will depreciate at 2.5/ (2.5+1.5+0.5)= 2.5/4.5 = 0.555 of the capital cost for the first 365 days, 1.5/4.5 =0.333 for the next 365 days, and 0.5/4.5 = 0.111 for the remaining 183 days. Again, this is a step function. Using the per period method (=0), you may enter the life as a fraction of a period, although it would be unusual to do so.

Formula used by DepnSYD

(Depreciation, period p) = c * (n - p + 1)/(n*(n+1)/2) Where: c = capitalization, n = life of the asset, p = period for which depreciation is being calculated

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the calculation cell of the item to which you want to apply the BiF - in this case, Depreciation. 3. Click Change item attributes. 4. Click BiF. 5. Select DepnSYD from the Function Name list. 6. Click Next. 358 Analyst

Chapter 12: Built in Functions (BiFs) 7. Double-click the parameters in the BiF Function Wizard. Note: The parameter indicator should be typed in as a constant. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Deytd
Original=@Deytd(Year to Date series) Input/Output Parameter
Year to Date series Original Input BiF Result D-List Item D-List Item

Description
Accumulated total (Year to date Sales) Original series (sales)

How Deytd Works

Re-starts at start of fiscal year, in this example set to 1st April in the timescale D-List.

Jan
YTD Sales Monthly Sales 1000 1000

Feb
2000 1000

Mar
3000 1000

Apr
2,000 2000

May
4000 2000

Jun
6000 2000

Jul
8000 2000

Aug
10000 2000

Sep
12000 2000

Deytd calculates the original numbers in one row based on the year-to-date figures in another row. Totals restart at the first period of each fiscal year. The start date for the fiscal year is set in the timescale D-List. If no fiscal year start date is set in the timescale D-List, it defaults to the January 1st. Deytd is designed for cases when the timescale D-List starts in January and ends in December, the fiscal year start, however, is not in January.

Formula used by Deytd

Original, period n = (Year to Date Value, Period n) - (Year to Date Value, Period n-1) Except at the beginning of the fiscal year when Original, Period 1 = Year to Date value, Period 1

User Guide 359

Chapter 12: Built in Functions (BiFs)

To set up the Deytd Timescale

A fiscal year start is required. Specify the day and month.

Steps
1. Open a timescale D-List. 2. From the D-List menu, click Options. 3. Click the TimeScale tab. 4. Set the day and month for Start of fiscal year. 5. Specify a Switchover date if needed. 6. Save the timescale D-List.

To set up the Deytd Calculation Steps

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case Sales Breakdown. 3. Click Change item attributes. 4. Click BiF. 5. Select Deytd from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Differ
Difference=@Differ(Base;Style) Input/Output
Base Input

Parameter
D-List Item

Description
The data to compare

360 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output
Style Input

Parameter
% a p

Description
Percent difference arithmetic difference proportion difference The difference

Difference

BiF Result

D-List Item

How Differ Works

Differ calculates the difference between the current and previous time periods. The difference may by expressed in the style of a percentage, proportion, or straight forward arithmetic difference. Three examples are shown: Difference-% = @Differ({Base Sales}; % ) = ((current - last) / last) * 100 Difference-arithmetic = @Differ({Base Sales}; a ) = (current - last) Difference-proportion = @Differ({Base Sales}; p ) = (current/last)

Formulas used by Differ

Three different formulas are possible in the BiF result depending on whether the parameter, Style, is set to % (percentage), a (arithmetic), or p (proportion difference). Differ = @Differ(Base;Style) The formula for a percentage difference is: Differ, period n = @Differ(Base;% ) = 100*(((Base,period n) - (Base period n-1))/(Base, period n)) The formula for an arithmetic difference is: Differ, period n = @Differ(Base; a ) = (Base, period n) - (Base, period n-1) The formula for a proportion difference is: Differ, period n = @Differ({Base Sales; p ) = (Base, period n)/(Base, period n-1)

Jan
Base Differ Percentage 1000 0

Feb
2000 100%

Mar
4000 100%

Apr
5000 25%

May
2000 (60)%

Jun
1000 (50)%

Jul
0 (100)%

User Guide 361

Chapter 12: Built in Functions (BiFs)

Jan
Differ Arithmetic Differ Proportion 0

Feb
1000

Mar
2000

Apr
1000

May
(3000)

Jun
(1000)

Jul
(1000)

200%

200%

125%

40%

50%

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case Difference (Percentage). 3. Click Change item attributes. 4. Click BiF. 5. Select Differ from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Drive
Forecast=@Drive(History;Switchover;Drivers) Input/Output
History Switchover Date Input Input

Parameter
D-List Item

Description
The base cost The switchover date defines the first future period

None 19970501 DList

= Treat all periods as historic May 1, 1997 Use switchover date in timescale D-List

362 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output

Parameter
Today 5

Description
Use today's date Use May in monthly timescale D-List A driver is something that drives the cost (headcount, floor space, unit price, and so on. Any number of drivers are allowed. The forecast cost

Driver 1 to n

Input

D-List Item

Forecast

BiF Result

D-List Item

How Drive Works

Drive calculates the forecast for future periods using historical data and as many drivers as are needed. A driver is something that drives the cost, for example, Headcount, floorspace, units sold, unit price, and so on). If one of the original drivers is set to zero, it will not have an effect on the forecast. For one or two drivers, the other built-in functions Drive1 or Drive2 can be used to monitor the effect of each driver separately. In the example that follows, the drivers are Price, Units, and Exchange rate. A forecast is calculated based on applying fluctuations in these drivers to a historical base value. The switchover date is set as May 1st in the timescale D-List so April is set as the base month. April contains a historical base value of 10000. Forecast = @Drive(History;Dlist;{Driver1-Units};{Driver2-Price};{Driver3-Exchange Rate})

Apr
History Driver 1 - Units Driver 2 - Price Driver 3 - Exchange Rate Forecast 10000 10 5 10 10000

May

Jun

Jul

Aug

Sep

10 6 10 12000

10 6 10 12000

10 6 10 12000

12 7 10 16800

13 8 11 22880

In the example shown, the number of units, the price, and the exchange rate have all risen by September. The forecast for September is worked out as follows: September Forecast = Historical cost in April * Ratio1* Ratio2 * Ratio3 = 10000 * (13/10) * (8/5) * (11/10)

User Guide 363

Chapter 12: Built in Functions (BiFs) = 22880 Other examples show the use of different switchover date parameters: Forecast = @Drive(History;Today;{Driver1-Units};{Driver2-Price};{Driver3-Exchange Rate}) uses todays date as a switchover date. Forecast = @Drive(History;19960501;{Driver1-Units};{Driver2-Price};{Driver3-Exchange Rate}) uses 1st May 1996 as a switchover date. Note: If the switchover date is set outside the dates defined in the timescale D-List, the base period will default to the first period.

Formulas used by Drive

The forecast is worked out as follows: Forecast, Period n = (History, Period p) * Ratio 1 * Ratio 2 * . . . * Ratio n Where: Ratio 1 = (Driver 1, Period n) / (Driver 1, Period p) Ratio 1 = (Driver 2, Period n) / (Driver 2, Period p) Ratio 1 = (Driver 3, Period n) / (Driver 3, Period p) Period n denotes the current period and Period p denotes the base period immediately prior to the switchover date. Period p is the last period to contain historical data. From that period on the data is forecast.

Set Up the Drive Timescale Steps

1. Open the timescale D-List. 2. From the D-List menu, click Options. 3. Click the Timescale tab. 4. Select Use Switchover and enter a date. 5. Save the timescale D-List.

Set Up the Drive Calculation Steps

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case Forecast. 3. Click Change item attributes. 4. Click BiF.

364 Analyst

Chapter 12: Built in Functions (BiFs) 5. Select Drive from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: Specify Use Switchover In the Use Switchover box, you have several options, they are as follows: Type Dlist to use the switchover date defined in the timescale D-List Type Today to use todays date Type a date (for example, 19990609) to specify a date Type a number (for example, 5) to specify a generic month Type None to treat all periods as historic Switchover parameters entered in the BiF formula will override the switchover date contained in the timescale D-List.

8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Drive1
Forecast=@Drive1(History;Switchover;Driver;Effect) Input/Output
History Driver Input Input

Parameter
D-List Item D-List Item

Description
The base cost A driver is something that drives the cost (headcount, floor space, unit price, and so on. Any number of drivers are allowed.

Effect

Output

D-List Item Incremental effect of an increase in driver The switchover date defines the first future period None = treat all periods as historic

Switchover Date

Input

User Guide 365

Chapter 12: Built in Functions (BiFs)

Input/Output

Parameter
19970501 DList

Description
May 1, 1997 Use switchover date in timescale D-List Use today's date Use May in monthly timescale D-List The forecast cost

Today 5

Forecast

BiF Result

D-List Item

How Drive1 Works

Drive1 calculates the forecast for future periods using historical data and a single driver. It shows the incremental effect of the driver on the historical base figure. The forecast is based on the ratio of the driver value at a future time to the driver value for a base period. The base period is defined as the last period containing historical data, namely the period before the switchover date. In the example shown, the switchover date has been set as May 1st in the timescale D-List. In April and any month prior to the switchover date, the forecast uses historical data. From May onwards the forecast is worked out by multiplying the base cost in April by the ratio of the driver in the given month to the driver in April. May Forecast = (Apr, History) * (May, Driver) / (Apr, Driver) = 10000 * 11/10 = 11000

Apr
History Rate Effect Forecast 10000 10 0 10000

May

Jun

Jul

Aug

Sep

11 1000 11000

11 1000 11000

11 1000 12000

12 2000 12000

12 2000 12000

Formulas used by Drive1

The forecast and effect are worked out as follows: Forecast = h * (c / o) Effect = h * (( c / o )- 1 ))

366 Analyst

Chapter 12: Built in Functions (BiFs) where: c = Current Driver o = Original Driver h = Historical base cost in period before switchover date

To set up the Drive1 timescale

Specify Use Switchover

Steps
1. Open the timescale D-List. 2. From the D-List menu, click Options. 3. Click the Timescale tab. 4. Select Use Switchover and enter a date. 5. Save the timescale D-List.

To set up the Drive1 calculation Steps

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Forecast. 3. Click Change item attributes. 4. Click BiF. 5. Select Drive1 from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: Specify Use Switchover In the Use Switchover box, you have several options are as follows: Type Dlist to use the switchover date defined in the timescale D-List. Type Today to use todays date. Type a date (for example, 19990609) to specify a date. Type a number (for example, 5) to specify a generic month. Type None to treat all periods as historic. Switchover parameters entered in the BiF formula will override the switchover date contained in the timescale D-List.

User Guide 367

Chapter 12: Built in Functions (BiFs) 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Drive2
Forecast = @Drive2(History;Switchover;Driver1;Driver2;Effect1;Effect2;Interaction)

Input/Output Parameter
History Driver1 Input Input D-List Item D-List Item

Description
The base cost A driver is something that drives the cost (headcount, floor space, unit price, and so on. Any number of drivers are allowed. A second driver Incremental effect of an increase in driver Incremental effect of an increase in second driver The small incremental effect between the drivers The switchover date defines the first future period = treat all periods as historic

Driver2 Effect Effect2

Input Output Output

D-List Item D-List Item D-List item

Interaction Switchover Date

Output Input

D-List Item None

19970501 DList Today 5 Forecast BiF Result D-List Item

May 1, 1997 Use switchover date in timescale D-List Use today's date Use May in monthly timescale D-List The forecast cost

How Drive2 works

Drive2 calculates the forecast for future periods using historical data and two drivers. It also calculates the incremental effect of each driver on the historical base figure.

368 Analyst

Chapter 12: Built in Functions (BiFs) In the example shown the drivers are Price and Volume. The switchover date is set at May 1st. Note that the total incremental effect is not just the sum of price and volume effects. There is a small interaction effect of a price increase on just the extra units of volume. The forecast for May is calculated as follows: Effect1 Price = = = Effect2 Volume = = = Interaction = (May price/base price in April) * historic sales in April 11/10 * 1000 100 (May volume/base volume in April) * historic sales in April 120/100 * 1000 200 (May volumes * May prices) - (Apr volumes * Apr prices) Effect1 - Effect2 20 Historic sales in April + Price effects + Volume effects + 1000 + 100 + 200 + 20 1320

= Forecast May Interaction = = =

Forecast = @Drive2({Historic Sales};Dlist;{Driver1 Price};{Driver2 Units};{Effect1 Price};{Effect2 Volume};Interaction)

Jan
Historic Sales Driver 1: Price Driver 2: Volume Effect 1: Price Effect 2: Volume Interaction 1000 10 100

Feb
1000 10 100

Mar
1000 10 100

Apr
1000 10 100

May

Jun

Jul

Aug

11 120 100 200 20

11 100 100 0 0

10 120 0 200 0

11 124 100 240 24

User Guide 369

Chapter 12: Built in Functions (BiFs)

Jan
Forecast Sales 1000

Feb
1000

Mar
1000

Apr
1000

May
1320

Jun
1100

Jul
1200

Aug
1364

Formulas used by Drive2

The forecast is calculated as a function of a base historical value and the two drivers. The base historical period is the period immediately prior to the switchover date. The forecast period is denoted by period n. Effect1, period n Effect2, period n Interaction, period n = = = ((Driver1, period n)/(Driver1, base period)) * (History, base period) ((Driver2, period n)/(Driver2, base period)) * (History, base period) +((Driver1, period n) * (Driver2, period n)) - ((Driver1, base period) * (Driver2, base period)) - ((Effect1, period n) - (Effect2, period n)) Forecast, period n = +(History, base period) +(Effect1, period n) +(Effect2, period n) +(Interaction, period n)

To set up a Drive2 timescale

Specify Use Switchover

Steps
1. Open the timescale D-List. 2. From the D-List menu, click Options. 3. Click the Timescale tab. 4. Select Use Switchover and enter a date. 5. Save the timescale D-List.

Set up a Drive2 calculation Steps

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Forecast Sales. 370 Analyst

Chapter 12: Built in Functions (BiFs) 3. Click Change item attributes. 4. Click BiF. 5. Select Drive2 from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: Specify Use Switchover In the Use Switchover box, you have several options as follows: Type Dlist to use the switchover date defined in the timescale D-List. Type Today to use todays date. Type a date (for example, 19990609) to specify a date. Type a number (for example, 5) to specify a generic month. Type None to treat all periods as historic. Switchover parameters entered in the BiF formula will override the switchover date contained in the timescale D-List. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@ErlangDelayAgents
The @ErlangDelayAgents built-in function returns a calculation for the number of agents that are required to meet the call center service levels. ErlangDelayAgents makes calculations which are too complex to express in regular planning formula. (Agents; LevelFound; LowerLevel; C; LowerC) = @ ErlangDelayAgents (Method; SLA; ServiceTime; CallsPerHour; AHT)

Name
Method SLA

Input/Output
Input Input

Description
1 = Fractional Agents. Otherwise Whole Agents (default) Service Level - the proportion of calls that reach an agent in time The critical average waiting time in seconds before a call reaches an agent The average number of calls received in an hour

ServiceTime

Input

CallsPerHour

Input

User Guide 371

Chapter 12: Built in Functions (BiFs)

Name
AHT LevelFound LowerLevel C LowerC Agents

Input/Output
Input Output Output Output Output Result

Description
The average handling time = call duration in seconds Level given by the next whole number of agents up Level given by the next whole number of agents down Erlang C for next whole number of agents up Erlang C for next whole number of agents down The number of agents required

How ErlangDelayAgents Works

ErlangDelayAgents returns a calculation for the number of agents that are required to meet the call center service levels. It is not a true Time BiF. It has no understanding of time as it is represented by Planning timescales. Rather, it uses a way of presenting complex iterative calculations that can not be performed by regular Planning formula, although a D-Cube must contain some sort of timescale for the BiF to function. See "Understanding the Erlang BiFs Equations" (p. 376) for full details on the equations used here. Also see the "Erlang Built-in Functions Glossary" (p. 378) for information on terminology relating to the Erlang built-in functions.

Error Messages
[E CX00591] @ErlangDelayAgents SLA must be less than 1 in period(s) "two" and slice(s) "d" at erlang.errors[Fractional Agents]. SLA must be less than 1: Service level agreement is a probability so it must lie between 0 and 1. A value of zero is a silent error. [E CX00591] @ErlangDelayAgents SLA has been reduced to 0.99999 in period(s) "two" and slice(s) "e" at erlang.errors[Fractional Agents]. SLA has been reduced to 0.99999: The program checks if (1-SLA) (the probability that a call waits longer than the ServiceTime) is less than 0.00001. This value is hard coded into the program. [E CX00591] @ErlangDelayAgents floating point overflow during preamble in period(s) "one" and slice(s) "b" at erlang.errors[Fractional Agents]. Floating point overflow during preamble: The fix is to change your inputs. The equations at risk are: DeathRate =3600 / AHT; Intensity = BirthRate / DeathRate. [E CX00591] @ErlangDelayAgents floating point overflow during convergence in period(s) "one" and slice(s) "d" at erlang.errors[Fractional Agents].

372 Analyst

Chapter 12: Built in Functions (BiFs) Floating point overflow during convergence: This is where, for example, a divide creates a number that is too big to handle during convergence (looking for the number of servers that meet the service level).

@ErlangDelayFull
The @ErlangDelayFull built-in function returns a calculation for the proportion of calls that will be queued because there are no agents available when the call was answered. (SLP; Death Rate; ...; CritQLengthProb) = @ErlangDelayFull(Agents; CallsPerHour; AHT; ServiceTime; CritQueueTime; CritQueueLength)

Name
Agents CallsPerHour AHT ServiceTime

Input/Output
Input Input Input Input

Description
The number of agents available The average number of calls received in an hour The average handling time = call duration in seconds The critical average waiting time in seconds before a call reaches an agent CQT = critical time in seconds that a call remains in the queue once it is put there. Critical Queue Length (may be negative) 3600/AHT = average number of calls handled per hour by one agent Traffic Intensity = BirthRate / Death Rate = TrafficRate / Agents. What proportion of an average agents time is spent handling a call. Erlang Loss Function Erlang Delay Function Average queue time, once a call is put in the queue Average number of calls in the queue Average time in which a call reaches an agent

CritQueueTime

Input

CritQueueLength DeathRate

Input Output

TrafficRate Utilization

Output Output

ErlangB ErlangC AvgQueueTime AvgQueueLength AvgTimeToAgent

Output Output Output Output Output

User Guide 373

Chapter 12: Built in Functions (BiFs)

Name
CritQTimeProp

Input/Output
Output

Description
Proportion of calls in queue for longer than critical queue time Probability that number of calls in queue is greater or equal to critical queue length. When critical queue length is negative, it is the probability that the number of idle agents (those not answering a call) is (-criticalqueuelength) or fewer, or the probability that at least (Agents + CriticalQueueLength) agents are busy. The calculations are recursive, starting with j=s, and working back until j=k, where: k = s + CQL;

CritQLengthProb

Output

SLP Notes:

Result

Service Level Provided

Agents is rounded up to a whole number before calculation starts. Agents must be greater than intensity, otherwise the calculations are not made and a message is added to the calculation errors. Service Time and AHT need not be a whole number of seconds.

How ErlangDelayFull Works

ErlangDelayFull returns a calculation for the proportion of calls that will be queued because there are no agents available when the call was answered. This BiF calculates both the Erlang B and C formula, along with Utilization, Service Level Provided, and Average QueueTime. ErlangDelayFull has the ErlangC calculation as one of its outputs. The Erlang C calculation is also known as the Erlang Delay Function, and as Congestion in a Blocked Calls Delayed operation. It is the proportion of calls that will be queued because there are no agents available when the call was answered. The results can be whole or fractional depending on the method parameter of BiF. The default method is whole. ErlangDelayFull does not perform fractional calculations. For example, no fractional ErlangC, although it is possible to calculate this manually: ErlangC=ErlangB / (((Intensity / NoAgents) * ErlangB) + (1 - (Intensity / NoAgents)))). See "Understanding the Erlang BiFs Equations" (p. 376) for full details on the equations used here. Also see the "Erlang Built-in Functions Glossary" (p. 378) for information on terminology relating to the Erlang built-in functions.

374 Analyst

Chapter 12: Built in Functions (BiFs)

@ErlangDelayLite
The @ErlangDelayLite built-in function is similar to the @ErlangDelayFull built-in function, except that the key output is utilization. (Utilization; Death Rate; Birth Rate) = @ErlangDelayLite(Agents; CallsPerHour; AHT)

Name
Agents CallsPerHour AHT DeathRate

Input/Output Description
Input Input Input Output The number of agents available The average number of calls received in an hour The average handling time = call duration in seconds 3600/AHT = average number of calls handled per hour by one agent BirthRate / Death Rate = Traffic Intensity TrafficRate / Agents. What proportion of an average agents time is spent handling a call.

TrafficRate Utilization

Output Result

How ErlangDelayLite Works

ErlangDelayLite is similar to ErlangDelayFull. The key output is utilization. Utilization = Intensity / NumberOfAgents Where: Intensity = CallsPerHour*AverageHandleTime/3600 See "Understanding the Erlang BiFs Equations" (p. 376) for full details on the equations used here. Also see the "Erlang Built-in Functions Glossary" (p. 378) for information on terminology relating to the Erlang built-in functions.

@ErlangLossLite
The @ErlangLossLite built-in function calculates the proportion of calls blocked when the traffic offered is answered by this number of servers, with no queue being held. So a call made when all servers are busy is not answered. This is called the Blocked Calls Cleared model. ErlangB = @ErlangLossLite(Agents; Intensity)

Name
Agents Intensity

Input/Output
Input Input

Description
The number of agents available Traffic intensity - calls arriving per hour/calls serviced per hour by one server/agent

User Guide 375

Chapter 12: Built in Functions (BiFs)

Name
ErlangB

Input/Output
Result

Description
The proportion of incoming calls lost in the long run

All of these actions are taken silently: Negative intensity and agents inputs are treated as zero Agents values with fractions are increased to a whole number If intensity is zero, then B is set to zero If agents is zero and intensity is non-zero, then congestion is set to one If a domain error occurs, then B is set to zero

How ErlangLossLite Works

ErlangLossLite calculates the proportion of calls blocked when the traffic offered is answered by this number of servers, with no queue being held. So a call made when all servers are busy is not answered. This is called the Blocked Calls Cleared model. ErlandLossLite calculates the ErlangB equation. See "Understanding the Erlang BiFs Equations" (p. 376) for full details on the equations used here. Also see the "Erlang Built-in Functions Glossary" (p. 378) for information on terminology relating to the Erlang built-in functions.

Understanding the Erlang BiFs Equations

This section lists the equations used by the Erlang BiFs so you can understand what they are calculating. Some of the simpler equations are described in the Erlang glossary. This section describes the more complex equations, plus the outputs of @ErlangDelayFull that do not appear in the table.

Useful Identities
Some of the equations can be expressed in two different ways: (1 - {rho}) * s = s - a or {mu} * ST / 3600 = ST / AHT The preferred usage is the second expression, which may disguise the equations you are expecting.

ErlangB
ErlangB uses the recursive equations: B[0, a] = 1; and B[s, a] = (a * B[s-1, a]) / (s + a * B[s-1,a] Where B[s, a] is ErlangB for {s} servers and intensity {a}.

376 Analyst

Chapter 12: Built in Functions (BiFs)

ErlangC
ErlangC is calculated from corresponding ErlangB: C[s, a] = B[s, a] / ( 1 - {rho} * ( 1 - B[s, a])

SLP
SLP is the service level provided by a given number of agents "s" and a given average service time {ST}: SLP = 1 - C[s, a] * {e}^((a - s) * ST / AHT) Where {e} is Euler's number.

Agents
The number of agents needed to provide a given SLA is the lowest whole number such that SLP >= SLA

AQT
The average waiting time in queue once a call is put in it is 1 / ((s - a) * {mu})

AQL
The average number of calls in the queue is (C[s,a] * {rho} / ( 1 - {rho})

ATA
The average time to agent is C[s, a] * AQT=Cs{AQT}

CQTP
The CQTP is the proportion of calls in the queue for longer than the critical queue time: {e} ^ ((a-s) * CQT / AHT) Where {e} is Euler's number.

CQLP
When critical queue length is positive, CQLP is the probability that the number of calls in the queue is greater or equal to the critical queue length: C[s, a] * {rho} ^ CQL When CQL is negative, the value returned represents the probability that (-{CQL}) or fewer of the agents are free to answer a call when it arrives, or the probability that at least (Agents + CriticalQueueLength) agents are busy. The calculations are recursive. Working back from CQL = 0, one agent at a time, they are:

User Guide 377

Chapter 12: Built in Functions (BiFs) Stop when you know CQLP[j] for j = s + {CQL}; delta[s-1] = C[s,a] * ((s/a)-1); CQLP[s-1] = delta[s-1] + C[s,a] = C[s,a]*s/a. Then, for each j: delta[j-1] = delta[j]*j/a; CQLP[j-1] = delta[j-1] + CQLP[j]

Erlang Built-in Functions Glossary

This glossary shows the currently used terms, their meaning, and their relationship with other terms.

Term
AHT

Description
Average Handling Time of a call in seconds, including the after call work. Need not be a whole number.

Equation
AHT = User Input

Death Rate

The average number of calls handled by a single {mu} = 3600/AHT agent in an hour. The number of calls arriving per hour, (BirthRate) Also known as Erlangs; Traffic Rate; Traffic Offered; ... {lambda} = CPH = User Input a = {lambda} / {mu}

CallsPerHour

Intensity

Agents

The (number of) agents answering the phone at s =User Input or s = the call centre. Also known as Servers. @ErlangDelayAgents The average load on the agents. {rho} = a / s

Utilization ErlangB

The proportion of calls blocked (not answered) B = @ErlangLossLite in a blocked calls cleared operation. The proportion of calls placed in the queue in a C = @ErlangDelayFull blocked calls delayed operation. The average time in seconds a call waits in the AQT = @ErlangDelayFull queue, once it is placed there, before it gets to an agent. The average time a calls takes from the moment AHT + C * AQT it arrives to the time it is completed. The desired target average time in seconds that ST = User Input should not often be exceeded before a call arrives at an agent. Need not be a whole number.

ErlangC

WaitingTime

Total Time

ServiceTime

378 Analyst

Chapter 12: Built in Functions (BiFs)

Term
SLA

Description
Service Level Agreement, the desired average proportion of calls that should reach an agent before the ServiceTime is up.

Equation
User Input

@Feed
Closing=@Feed(Prime;Opening;In;Out) Input/Output
Prime Input

Parameter
D-List Item or Constant D-List Item

Description
The opening balance of the first (default = 0)

Opening

Output

The opening balance of each subsequent period, fed from closing balance of the previous period Inflow or incremental amount Outflow or decremental amount Closing balance (Closing cash balance)

In Out Closing

Input Input BiF result

D-List Item D-List Item D-List Item

How Feed works

Feed calculates the closing balance and "feeds" it to the opening balance of the next time period. In the first period only, the opening balance defined in the item, Prime. This parameter can either be a constant or a D-List item (If excluded, it has a default value of zero). Thereafter, the opening balance assumes the closing balance of the previous period. Closing=@Feed(Prime;Opening;In;Out)

Jan
Prime Opening In Out 5000 5000 2000 1000

Feb

Mar

Apr

May

Jun

6000 5000 1000

10000 6000 1000

15000 2000 1000

16000 3000 1000

18000 2000 1000

User Guide 379

Chapter 12: Built in Functions (BiFs)

Jan
Closing 6000

Feb
10000

Mar
15000

Apr
16000

May
18000

Jun
19000

Formulas used by Feed

Closing Balance = Opening + In - Out Opening Balance, Period n = Closing Balance, Period n-1 Opening Balance, Period 1 = Prime, Period 1

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Closing. 3. Click Change item attributes. 4. Click BiF. 5. Select Feed from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@From(Closing) calculation
The opening balance calculation contains the word, Output, in the D-List attribute screen. Click it and you see the calculation, @From(closing), appear. You cannot edit or remove this. It indicates that the opening balance in one period is calculated as equal to the closing balance from the previous period.

@FeedParam
Closing=@FeedParam(Param;Prime;Opening;In;Factor;Out) Input/Output
Param Input

Parameter

Description
The parameter used to modify the equation for the parameter Out. The factor is used as a percentage, fraction, or denominator.

380 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output

Parameter
% * /

Description
Out = Opening*Factor/100 (default) Out = Opening*Factor Out = Opening/Factor The opening balance of the first period (default=0) The opening balance of each period; fed from closing balance of previous period. Inflow or Incremental amount Outflow or Reduction calculated using the Opening balance, parameter and factor The factor to apply to the opening balance when calculating the parameter, Out (can be multiplied, divided, or taken as a percentage depending on the value of Param. Closing balance (closing cash balance)

Prime

Input

D-List Item or Constant D-List Item

Opening

Input

In Out

Input Output

D-List Item D-List Item

Factor

Input

D-List Item

Closing

BiF Result

D-List Item

How FeedParam works

FeedParam calculates the closing balance and feeds it to the opening balance of the next period. It calculates the outflow as a function of the opening balance. The FeedParam calculation is commonly used to predict closing balances for use in the balance sheet. It is used when the outflow is a function of the opening balance such as tax payments, periodic payments, and accruals or wastage calculations. For example, Out = 50% of Opening balance. For the first period only, the opening balance is defined in the item Prime. This can either be a constant or a D-List item. If left out, it has a default value of zero. Thereafter, the opening balance assumes its value from the closing balance of the previous period. For example, suppose you wish to pay off 50% of the opening balance in June. The factor of 50% is entered as a factor in June and the calculation parameter set to % to calculate the outflow as a percentage of the opening balance. Closing = @FeedParam(%;Prime;Opening;In;Factor;Out)

Jan
Prime 5000

Feb

Mar

Apr

May

Jun

User Guide 381

Chapter 12: Built in Functions (BiFs)

Jan
Opening In Factor Out Closing 5000 1000 0 0 6000

Feb
6000 1000 0 0 7000

Mar
7000 1000 50 3500 4500

Apr
4500 1000 0 0 5500

May
5500 1000 0 0 6500

Jun
6500 1000 0 0 7500

Formulas used by FeedParam

Out = Opening * Factor / 100 For Param set to % Out = Opening * Factor For Param set to * Out = Opening / Factor For Param set to / Closing = Opening + In - Out Opening, Period 1 = Prime, Period 1 Opening, Period n = Closing, Period n-1

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Closing. 3. Click Change item attributes. 4. Click BiF. 5. Select FeedParam from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. Note: When typing items into the Param box, you have several options: Type % to imply Out = Opening * Factor/100 Type * to imply Out = Opening * Factor Type / to imply Out = Opening / Factor 8. Click Finish. 9. Click Apply. 10. Save the D-List. 382 Analyst

Chapter 12: Built in Functions (BiFs)

@Forecast
Forecast = @Forecast(Budget, Actual, ActFor Flag, Override, Method, Indicator, n or flag, Days in Period) Input/Output Parameter
Budget Actual ActFor Flag Input Input Input D-List Item D-List Item D-List Item

Description
The budget amount The actual amount Usually a D-List formatted item using IIDs of 1= Actual, 2 = Forecast. Note: If, by mistake, the flag is not a 1 or 2, the forecast is not calculated, except for methods Goal, Periodic, Subtotal and Full-term where it is treated as a forecast period.

Override

Input

D-List Item

The new forecast used to override the budget if the method = 2, override 1=Act/Bud, 2=Override, 3=Trend, 4=Goal, 5=Average, 6=Linear, 7=Periodic, 8=Subtotal, 9=Full-term. The method would be entered as a number (or a D-List formatted item that happened to have the same IID) in the earliest chronological time period. 0 = no. periods (default) 1 = Use Days in Period. If value found in Days in Period is illegal, (zero or negative), then ignore this period and go on to the next. 2 = Use days from timescale D-List.

Method

Input taken D-List Item from earliest period where a valid method has been specified

Indicator

Input

D-List Item or Constant

User Guide 383

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
n or flag Input D-List Item or Constant

Description
If method = 5 - Average, or 6 - Linear, this input tells you the number of actual periods over which to average or extrapolate the daily rate. If zero or negative, use all actual periods. Note: 'n' can vary by period if need be. If method = 7 - Periodic, this input is used to flag the period. A one (1) is entered into the period to be used as the final period for adjusting the forecast to match the cumulative budget.

Days in Period Forecast

Input BiF Result

D-List Item D-List Item The revised forecast based on a combination of actual and forecast amounts

How @Forecast Works

@Forecast combines actual and forecast data to produce a rolling forecast. It would allow you to forecast the future months based on the performance to date, using any of the following methods: Act/Bud = Use actuals for historic periods, and budget for future periods. A flag indicates whether a period is a historic or future period. Override = Enter your own forecast manually, overriding the original budget. Trend% = Follow the trend to date by working out the actuals to date as a percentage of the budget, and applying this percentage to the future budget. Goal = Scale future periods to meet the budget goal over the duration of the timescale. When the budgets for future periods are all zero, the forecast for these periods remains at zero too. Average = Forecast based on an average of actuals to date. Linear = Forecast using linear extrapolation. Periodic = Scale future periods to meet the cumulative budget goal between points in time defined by a flag. Subtotal = Scale future periods to meet the cumulative budget goal between points in time defined by subtotals in the timescale D-List. Full-term = Scale future periods to meet the budget goal over the duration of the timescale. When the budgets for future periods are all zero, spread any shortfall according to days in period so that the full-term forecast always matches the budget.

Note: The forecast method used is whichever one is specified in the first time period.

384 Analyst

Chapter 12: Built in Functions (BiFs)

Method 1: ActBud
Forecast=Actual where A/F Flag =1 (Actual), Budget where A/F Flag =2 (Forecast)

Jan
Budget Actual A/F Flag Override Days Indicator Periods Flag Method (1) Act/ For 800 0 1000 800 Act

Feb
1000 800 Act

Mar
2000 1200 Act

Apr
1000

May
1000

Jun
2000

Jul
2000

YEAR
10000 2800

For 1500

For 1500 0

For 1500 0

For 1500 0 6000 0

Forecast

800

1200

1000

1000

2000

2000

8800

Method 2: Manual
Forecast = Actual where A/F Flag =1 (Actual), Override where A/F Flag =2 (Forecast). In the example below, an override figure of 1,500 per period is used for all forecast periods.

Jan
Budget Actual A/F Flag Override Days Indicator 0 Periods Flag Method Forecast (2) Override 800 1000 800 Act

Feb
1000 800 Act

Mar
2000 1200 Act

Apr
1000

YEAR
5000 2800

For 1500 1500 0

800

1200

1500

4300

User Guide 385

Chapter 12: Built in Functions (BiFs)

Method 3: Trend
Works out the actuals to date as a percentage of the budget to date and applies this percentage to future periods. Forecast = Actual where A/F Flag =1 (Actual), but for future periods where A/F Flag =2 (Forecast) , Forecast = Budget *(Cumulative Actuals to date / Cumulative Budget to date), but if the cumulative budget to date is zero, then Forecast = Budget. In the example shown, actuals to date are running at 2800/4000 = 70% of budget.

Jan
Budget Actual A/F Flag Override Days Indicator Periods Flag Method (3) Trend% 800 0 1000 800 Act

Feb
1000 800 Act

Mar
2000 1200 Act

Apr
1000

May
1000

Jun
2000

Jul
2000

YEAR
10000

For 1500

For 1500 0

For 1500 0

For 1500 0 6000 0

Forecast

800

1200

700

700

1400

1400

7000

Method 4: Goal
Adjust the forecast periods such that the original full-term budget is met. The full-term budget is the sum of all detail periods in the budget row. Forecast = Actual where A/F Flag =1 (Actual), but for future periods where A/F Flag =2 (Forecast) , Forecast = Budget * (Full-term budget - actuals to date) / (full term budget - cumulative budget to date). In the example below, the forecast is adjusted for all future periods so the goal for the year meets the original budget of 2500; the adjustment applied to all the forecast periods is (2500-400)/ (2500-500)=1.05.

Period 1 Period 2 Period 3 Period 4 Period 5 Period 6 Total 60 days 61 days 61 days 62 days 61 days 61 days
Act/For Actual Actual Forecast Forecast Forecast Forecast

386 Analyst

Chapter 12: Built in Functions (BiFs)

Period 1 Period 2 Period 3 Period 4 Period 5 Period 6 Total 60 days 61 days 61 days 62 days 61 days 61 days
Budget Actual Method Indicator Number of Periods Forecast 150 250 210 420 630 840 2500 200 150 4 0 300 250 0 0 200 0 0 0 400 0 0 0 600 0 0 0 800 0 0 0 2500 400 4 0

Method 5: Average
Averages the daily rate from the last n actual periods and projects this forward. Forecast amount = avg actual daily rate x period length. An indicator is needed to set the period length: Indicator=0 means period length=1 Indicator=1 means period length is taken from days in period D-List item. If value found in Days in Period is illegal, zero or negative, then ignore this period and go on to the next. Indicator=2 means period length is taken from timescale D-List. You would also need a parameter 'n' to set the number of actual periods to average. This could be a constant or a D-List item. In this example it is set to 3. If there is no parameter set, then all actual periods are averaged. The indicator is set to zero so all periods are considered to be of equal length.

Period 1 Period 2 Period 3 Period 4 60 days 61 days 61 days 62 days

Act/For Budget Actual Method Indicator Actual 200 150 5 0 Actual 300 350 0 0 Actual 200 400 0 0 Forecast 400 0 0 0

Period 5 Period 6 61 Total 61 days days

Forecast 600 0 0 0 Forecast 800 0 0 0 2500 900 5 0

User Guide 387

Chapter 12: Built in Functions (BiFs)

Period 1 Period 2 Period 3 Period 4 60 days 61 days 61 days 62 days

Number of Periods Forecast 150 350 400 3

Period 5 Period 6 61 Total 61 days days

3 3 9

300

300

300

1800

Setting the Days Indicator to 2 will use the number of days within the timescale (the number indicated in the column headers) and gives the following results.

Period 1 Period 2 Period 3 Period 4 60 days 61 days 61 days 62 days

Period 5 61 days

Period 6 61 days
Forecast 800 0 0 0 3

Total

Act/For Budget Actual Method Indicator Number of Periods Forecast

Actual 200 150 5 2

Actual 300 350 0 0

Actual 200 400 0 0

Forecast 400 0 0 0 3

Forecast 600 0 0 0 3

2500 900 5 2 9

150

350

400

307

302

302

1810

Method 6: Linear
Fits a straight line through the last n actual points. Extrapolates the daily rate using least squares line of regression fitted to all actual periods: Forecast amount = projected daily rate x period length. An indicator is needed to set the period length: Indicator=0 means period length=1 Indicator=1 means period length is taken from days in period D-list item. If value found in Days in Period is illegal, zero or negative, then ignore this period and go on to the next. Indicator=2 means period length is taken from timescale D-List. You would also need a parameter 'n' to set the number of actual periods to average or to fit a straight line to. This could be a constant or a D-List item.

388 Analyst

Chapter 12: Built in Functions (BiFs) Setting the number of periods, n, as 2 uses the actual results for Period 2 and Period 3 to create the straight line. As the difference between Period 2 and Period 3 is 400 this is used as the gradient of the straight line therefore each forecast period shows an increase of 400 on the prior period.

Period 1 Period 2 Period 3 Period 4 60 days 61 days 61 days 62 days

Act/For Budget Actual Method Indicator Actual 200 150 6 0 Actual 300 100 0 0 Actual 200 500 0 0 Forecast 400 0 0 0 2

Period 5 61 days
Forecast 600 0 0 0 2

Period 6 61 days
Forecast 800 0 0 0 2

Total

2500 750 6 0 8

Number of 2 Periods Forecast 150 100 500

900

1300

1700

4650

Setting the Days Indicator to 2 will use the number of days within the timescale and gives the following results.

Period 1 Period 2 Period 3 Period 4 60 days 61 days 61 days 62 days

Act/For Budget Actual Method Indicator Number of Periods Forecast Actual 200 150 6 2 2 Actual 300 100 0 0 Actual 200 500 0 0 Forecast 400 0 0 0 2

Period 5 61 days
Forecast 600 0 0 0 2

Period 6 61 days
Forecast 800 0 0 0 2

Total

2500 750 6 2 8

150

100

500

918

1307

1707

4681

User Guide 389

Chapter 12: Built in Functions (BiFs)

Method 7: Periodic
Method 7=Periodic adjusts the forecast so that the cumulative budget is achieved at certain points in time marked by a flag. The flag is set by typing a 1 in the period where a re-forecast is required. At this point, it would look at actuals to date and re-forecast such that the cumulative forecast matches the cumulative budget. Any shortfall required to meet the budget is allocated by multiplying the original budget by a scaling factor. If necessary, the forecast will go negative to get you back on budget. It will only re-forecast future periods, or periods in which the actual/forecast flag is set to 2 (as in the examples, a D-List item named Forecast with an IID of 2). If a second or subsequent flag is set, the forecast is adjusted such that the cumulative forecast matches the cumulative budget between flags. In the special case where the budget is zero for all forecast periods between flags, then any shortfall required to meet the budget is spread according to days in period, or evenly if no from and to dates are defined. For example, to re-forecast on an annual basis, you would set flag =1 every December. In the first year, it would re-forecast for future periods so that the cumulative forecast for the year matches the cumulative budget for the year. As actuals are entered for year 2, it would continually re-forecast so as to meet the cumulative annual budget for year 2, disregarding the results from the previous year. By not setting the period flag, option 7 behaves in an identical manner to (9) Full-term, and ensures that the total of the budget across the timescale is achieved. In this case the sum of Year 1 and Year 2 is 12,500 so the forecast recalculates the values for the budget in all the forecast periods to achieve this result.

Q1
Budget Actual A/F Flag Override Days Indicator Periods Flag Method (7) Periodic 800 0 1000 800 Act

Q2

Q3

Q4

Year 1 Q1

Q2

Q3

Q4

Year 2

1000 1000 1500 4500 800 Act For For 1600

1000 4000 1000 2000 8000

For

For

For

For

For

Forecast

800

1038 1557 4195

1038 4152 1038 2076 8305

390 Analyst

Chapter 12: Built in Functions (BiFs) Setting the period flag in Q4 of year 1 will cause the variance in year 1 to be applied to the forecast periods within year 1 only.

Q1

Q2

Q3

Q4

Year 1 Q1

Q2

Q3

Q4

Year 2
8000

Budget Actual A/F Flag Override Days Indicator Periods Flag Method

1000 800 Act

1000 800 Act

1000

1500

4500 1600

1000

4000

1000

2000

For

For

For

For

For

For

For

(7) Periodic 800 800 1160 1740 4500 1000 4000 1000 2000 8000

Forecast

Method 8: Subtotal
Method 8= Subtotal is similar to Periodic, except that the break-points are set automatically to be the last period prior to each sub-total. For example, if you had three annual totals, the re-forecast would occur each year. Certain rules would apply when a detail timescale item belongs to more than one subtotal. If the budget is zero for all forecast periods between subtotals, any shortfall required to meet the budget is spread according to days in period. If no from and to dates are defined in the timescale, the shortfall is spread evenly.

Q1

Q2

Q3

Q4

Year 1
4500 1600

Q1

Q2

Q3

Q4

Year 2
8000

Budget Actual A/F Flag Override

1000 800 Act

1000 800 Act

1000

1500

1000

4000

1000

2000

For

For

For

For

For

For

For

User Guide 391

Chapter 12: Built in Functions (BiFs)

Q1

Q2

Q3

Q4

Year 1
0

Q1

Q2

Q3

Q4

Year 2
0

Days 0 Indicator Periods Flag Method (8) Sub Totals 800

Forecast

800

1160

1740

4500

1000

4000

1000

2000

8000

A timescale subtotal is recognized like this: It is a sum (all its operands are "+"). It is a sum of detail timescale items, with no constants or calculated items. The periods being summed are contiguous, there are no missing periods between the first and the last.

Method 8 expects you to define a set of timescale subtotals that span the whole timescale with no gaps or overlaps. When this is not the case, Method 8 identifies the last period of each subtotal as a way to correctly handle this. As a rule of thumb, ensure all formulas contain items at the finest level of detail. Here are some examples:

Formula
Q1=M1+M2+M3; Q2=M4+M5+M6; H1=Q1+Q2 Q1=M1+M2+M3; Q2=M4+M5+M6; H1= M1+M2+M3+M4+M5+M6 Q1=M1+M2+M3; H1= M1+M2+M3+M4+M5+M6 Q1=M1+M2+M3; Q2=M4+M5+M6; X= M2+M3+M4+M5

Last periods
M3, M6

Subtotals used
M1+M2+M3; M4+M5+M6

M3, M6

M1+M2+M3 M4+M5+M6

M3, M6

M1+M2+M3; M4+M5+M6

M3, M5, M6

M1+M2+M3; M4+M5; M6

392 Analyst

Chapter 12: Built in Functions (BiFs)

Method 9: Full-Term
Adjust the forecast periods such that the original full-term budget is met. The Full-Term budget is the sum of all detail time periods in the budget row. This is almost identical to Goal, but deals with the special case where the budget is zero for all future periods. This would work out the shortfall between actuals to date and the budget for the full-term of the timescale. Normally this shortfall would be spread over the future periods by scaling the budget figures by the same scaling factor. However, if the budgets for future periods are all zero, it would spread the shortfall according to the number of days in each period as defined in a timescale D-List. To assure the Analyst and Cognos Planning - Contributor results are consistent, an Indicator of 2 must be used when the BiF is set up in Analyst. The example below shows the full term effect; it ensures that the total of the budget across the timescale is achieved. Here the indicator is set at zero so all periods are considered to be of equal length and the 150 required to meet the overall budget over the whole timescale is spread evenly across the forecast periods.

Period 1 Period 2 Period 3 Period 4 Period 5 Period 6 Total 60 days 61 days 61 days 62 days 61 days 61 days
Act/For Budget Actual Method Indicator Number of Periods Forecast Actual 200 150 9 0 0 Actual 300 100 0 0 0 Actual 400 500 0 0 0 Forecast 0 0 0 0 0 Forecast 0 0 0 0 0 Forecast 0 0 0 0 0 900 750 9 0 0

150

100

500

50

50

50

900

If the indicator is set to 1, then the amount required to meet the budget is divided between the periods in accordance with the number of days input in the Days in Period row of the cube. If the indicator is set to 2, then the amount required to meet the total budget is divided between the periods in accordance with the number of days in each period as defined in the timescale.

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the @Forecast BiF.

User Guide 393

Chapter 12: Built in Functions (BiFs) 3. Click Change item attributes. 4. Click BiF. 5. Select Forecast from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Funds
Funds=@Funds(Assets; Sign) Input/Output
Assets Sign Input Input

Parameter
D-List Item + -

Description
The asset values Increase in assets display as positive numbers and source of funds display as negative numbers. Change the sign convention so that increase in assets display as negative numbers and source of funds display as positive numbers.

Funds

BiF Result

D-List Item

The use of funds

How Funds Works

Funds calculates the use of funds or the source of funds. A use of funds is either an increase in assets or a decrease in liabilities. The same BiF may be used to calculate the use of funds or source of funds simply by switching the sign parameter.

For example: @Funds(Assets;+)

Use of funds in July = (Asset value, July) - (Asset value, June) = 4000 - 3000 = 1000

Jan
Assets 1000

Feb
2000

Mar
3000

Apr
4000

May
8000

Jun
8000

394 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Funds 0

Feb
1000

Mar
1000

Apr
1000

May
4000

Jun
0

Formula used by Funds

Funds=@Funds(Assets; Sign) With the parameter sign positive, Funds calculates the use of funds. Funds=@Funds(Assets; +) Funds, Period n = (Assets, Period n) - (Assets, Period n-1) With the parameter sign negative, Funds calculates the source of funds. Funds = @Funds(Assets; -) Funds, Period n = (Assets, Period n-1) - (Assets, Period n)

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Funds. 3. Click Change item attributes. 4. Click BiF. 5. Select Funds from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@FV
FV = @PV(Nper; Rate; PMT; PV; Type; Payments; Opening Value; Closing Value; Interest Paid; Periods left) Input/Output
Nper Input

Parameter
D-List Item

Description
The number of periods the account is to run.

User Guide 395

Chapter 12: Built in Functions (BiFs)

Input/Output
Rate Input

Parameter
D-List Item

Description
Interpreted as a percentage but must be the rate per period. The constant payment applied to the account each period. The value of the account at the start of the calculation. 0 means the payment to the account is made at the end of the period and is the default. 1 means the payment to the account is made at the start of the period. The end value or closing balance of the account in the last period. Optional Item. Returns the value of PMT for every period in which the account operates. Optional item. If included, the BiF returns the opening balance of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period. Optional item. If included, the BiF returns the closing balance of the account. Will be equal to FV with the opposite sign in the last period of the account. Should be set as a time average, last period. Optional Item. If Type = 0 will equal Opening Value * Rate per Period/100. If Type = 1 will equal (Opening Value + Payment) * Rate per Period/100. Optional Item. Will be Nper in the first calculation period and will reduce by 1 in each subsequent period.

PMT

Input

D-List Item

PV

Input

D-List Item

Type

Input 0 or 1 only D-List Item

FV

Result

D-List Item

Payments

Output

D-List Item

Opening Value [start]

Output

D-List Item

Closing Output Value [end]

D-List Item

Interest Paid

Output

D-List Item

Periods left Output

D-List Item

How FV Works
FV calculates the closing balance for an account given the start balance and the conditions under which the account will run. The account must fulfill the following conditions: 396 Analyst

Chapter 12: Built in Functions (BiFs) The account runs for a set number of equal consecutive periods. A constant interest rate applies, compounded to the account at the end of each period (a zero rate is allowed). A payment of constant amount is applied to the account in each period. The user can apply the payment to the account either at the start or the end of the period.

Example 1 - A savings account

Consider a regular savings account. The interest rate is 0.5% per period. An investor opens the account with a deposit of 10000. The account runs for four periods. An investor pays in 500 per period. Payments are made at the end of each period. FV will calculate the amount which the investor will receive back from the account after four periods have elapsed.

So, in this example: PV = -10000 PMT = 500 Rate = 0.5 Nper = 4 Type = 0

It is possible to set this calculation against a single item D-List used as a timescale to produce the value for FV.

Calc (Timescale)
Present Value Payment per period Rate per period Number of periods Type Future Value 10000 500 0.5% 4 0 (12216.56)

User Guide 397

Chapter 12: Built in Functions (BiFs) Alternatively the calculation may be set against a longer timescale in which case the whole account will be scheduled - here the account is considered to start at period 2: Note: The calculation starts in the first period for which Nper is non-zero. Inputs to PV, PMT, Rate, Nper or Type in any other period will be ignored.

Period 1
Present Value 0

Period 2
10000

Period 3
0

Period 4
0

Period 5
0

Period 6
0

Payment per 0 period Rate per period Number of periods Type Future Value Opening Value Closing Value 0%

500

0.5%

0%

0%

0%

0%

0 0

0 (12216.56)

0 0

0 0

0 0

0 0

10000.00

10550.00

11102.75

11658.26

10550.00

11102.75

11658.26

12216.56

Interest Paid 0 Payments Periods left 0 0

50.00 500 4

52.75 500 3

55.51 500 2

58.29 500 1

0 0 0

Sometimes only part of the account falls within the timescale - in this case the account starts in period 5, and the closing balance value in the period 6 column indicates the balance of the account at the end of the timescale.

Period 1
Present Value 0

Period 2
0

Period 3
0

Period 4
0

Period 5
10000

Period 6
0

398 Analyst

Chapter 12: Built in Functions (BiFs)

Period 1
Payment per 0 period Rate per period Number of periods Type Future Value Opening Value Closing Value 0%

Period 2
0

Period 3
0

Period 4
0

Period 5
500

Period 6
0

0%

0%

0%

0.5%

0%

0 0

0 0

0 0

0 0

0 (12216.56)

0 0

10000.00

10550.00

10550.00

11102.75

Interest Paid 0 Payments Periods left 0 0

0 0 0

0 0 0

0 0 0

50.00 500 4

52.75 500 3

Example 2 - A series of loan contracts

Suppose you have three separate loans as follows

Start Period Number of Periods

Contract A Contract B Contract C Period 1 Period 1 Period 5 3 4 5

Rate per Period

0.5% 0.3% 0.6%

Initial Value Payment

10000 50000 5000

2500 10000 750

Using the FV BiF, it is possible to calculate the end value of each loan and make a schedule for each. It is also possible to split the payment each period into the amount used to pay interest and the amount of capital reduction. To do this, add an extra item to your calculation D-List named Capital Paid and set the calculation field for this item to be:

User Guide 399

Chapter 12: Built in Functions (BiFs) Payments + Interest Paid When creating the calculation D-Cube, this time there are three dimensions - FV Calculation, Periods, and Contracts. The Contracts D-List consists of the 3 contracts, A, B and C and a Total.

Step 1
Input the details of each contract on its own page, in the column for the relevant period. PV is input as a negative figure in each case because a payment is made from the loan account to the borrower. Periodic payments are then made from the borrower to the account to repay the loan so PMT is input as a positive figure.

Contract A
Present Value Payment per period Rate per period Number of periods Type Future Value Opening Value Closing Value Interest Paid Capital Paid Payments Periods left

Period 1
(10000) 2500

Period 2
0 0

Period 3
0 0

Period 4 Period 5 Period 6

0 0 0 0 0 0

0.5% 3

0% 0

0% 0

0% 0

0% 0

0% 0

0 2613.19 (10000.00) (7550.00) (50.00) 2450.00 2500 3

0 0 (7550.00) (5087.75) (37.75) 2462.25 2500 2

0 0 (5087.75) (2613.19) (25.44) 24747.56 2500 1

0 0 0 0 0 0 0 0

0 0 0 0 0 0 0 0

0 0 0 0 0 0 0 0

Step 2
After the details of each contract have been completed, go to the Total Contracts page to view the totals for each period.

400 Analyst

Chapter 12: Built in Functions (BiFs)

Contract Total Period 1

Present Value Payment per period (60000) 12500

Period 2
0 0

Period 3
0 0

Period 4
0 0

Period 5
(5000) 750

Period 6
0 0

Rate per period 0.8% Number of periods Type Future Value 7

0% 0

0% 0

0% 0

0.6% 5

0% 0

0 13035.53

0 0

0 0

0 0

0 1356.54

0 0 (4280.00) (3555.68)

Opening Value (60000.00) (47700.00) (35358.20) (20361.26) (5000.00) Closing Value (47700.00) (35358.20) (22974.45) (10422.35) (4280.00)

If the Timescale D-List you are using contains sub-total and Total fields, it will be necessary to set some items in the calculation D-Lists as Time Averages in order to obtain sensible figures in the Total Fields. D-List Item Present Value (PV) Payment per period (PMT) Rate per period (Rate) Number of periods (Nper) Type Future Value Opening Value Closing Value Interest Paid Capital Paid Last Period First Period Last Period Last Period Time Average First Period

User Guide 401

Chapter 12: Built in Functions (BiFs)

Payments Periods left Last Period

None of the Input items PV, PMT, Nper, Rate or Type give meaningful results against a Time Total because these are single column inputs, specific to the period to which they relate and it is not possible to aggregate them over time. However, the rows making up the account schedule (Payments, Opening Value, Closing Value, Interest Paid and Capital Paid) are meaningful in Time Total fields so long as the correct averages have been set as shown above.

Contract Total
Present Value

Period 1

Period 2

Period 3

Period 4

Period 5

Period 6

Total Periods
(60000)

(60000)

(5000)

Payment per 12500 period Rate per period Number of periods Type Future Value Opening Value Closing Value 0.8%

750

13250

0%

0%

0%

0.6%

0%

1.4%

0 13035.53

0 0

0 0

0 0

0 1356.54

0 0

0 0

(60000.00)

(47700.00)

(35358.20)

(20361.26)

(5000.00)

(4280.00)

(60000.00)

(47700.00)

(35358.20)

(22974.45)

(10422.35)

(4280.00)

(3555.68)

(3555.68)

Interest Paid (200.00) Capital Paid 12300.00 Payments Periods left 12500 7

(158.20) 12341.80 12500 5

(116.25) 12383.75 12500 3

(61.08) 9938.92 10000 1

(30.00) 720.00 750 5

(25.68) 724.32 750 4

(591.21) 48408.79 49000 4

402 Analyst

Chapter 12: Built in Functions (BiFs) Over the 6 periods, this company has paid 49000 in regular loan repayments. Of this, 591.21 was to cover interest and 48408.79 went to reduce the capital balances on the loans. Remember, however, that contracts A and B had outstanding balances on them at the end of their terms and these balances are not included in the Total Periods Payments figure.

Formulas Used by FV
Start[1+nper]=End[nper]=-FV If Rate = 0 Then FV =-( (PMT * Nper) + PV) If the rate is non-zero Then FV= -(( PV * (1 + Rate) Nper) + pmt(1 + (Rate* type)) *

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List. 2. Open the Calculation D-List. 3. Click the Calculation cell where you wish to calculate the FV result. 4. Click Change item attributes. 5. Click BiF. 6. Select FV from the Function Name list. 7. Click Next. 8. Enter the Nper parameter by selecting a D-List item. 9. Enter the Rate parameter by selecting a D-List item or typing a constant. If typing a constant, remember that it is the rate per period which should be entered. 10. Enter the PMT parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 11. Enter the PV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 12. Enter the Type parameter by selecting a D-List item or entering either 0 or 1. A 0 denotes payments made at the end of each period, and a 1 denotes payments made at the start of each period.

User Guide 403

Chapter 12: Built in Functions (BiFs) 13. Enter the Opening Value, Closing Value, Payments, Interest Applied, and Periods left parameters by selecting a D-List item for each. Completion of these fields is optional. 14. Click Finish. 15. Click Apply. 16. Save the D-List. Note: The Opening Value, Closing Value, Payments, Interest Applied, and Periods left calculation fields contain the word Output in the calculation field. Click this and you will see the calculation @From (FV). This field is calculated by the FV BiF, which cannot be edited or removed.

Messages and Input Ranges Multiple Accounts

For any slice of a cube, FV will only calculate a value in the first period where Nper is greater than zero. Inputs to fields in any subsequent time period will be ignored. The warning message, indicated by a yellow square in the top left-hand corner of the D-Cube, will be displayed. @FV only deals with one loan or annuity at a time. The calculation inputs are in Period xx for slice {slice name}. You have non-zero inputs in other periods - the first such period is Period xx, at {library name}, {cube name}[FV].

Period 1
Present Value (10000)

Period 2
0

Period 3
600

Period 4
0

Period 5
0

Period 6
0

Payment per 2500 period Rate per period Number of periods Type Future Value Opening Value 0.5%

30

0%

0.3%

0%

0%

0%

15

0 2613.19

0 0

0 0

0 0

0 0

0 0

(10000.00)

(7550.00)

(5087.75)

404 Analyst

Chapter 12: Built in Functions (BiFs)

Period 1
Closing Value (7550.00)

Period 2
(5087.75)

Period 3
(2613.19)

Period 4
0

Period 5
0

Period 6
0

Interest Paid (50.00) Capital Paid 2450.00 Payments Periods left 2500 3

(37.75) 2462.25 2500 2

(25.44) 24747.56 2500 1

0 0 0 0

0 0 0 0

0 0 0 0

The data entered into period 3 is ignored and the results shown are for the data in period 1 only. Where you wish to calculate a number of accounts, include a sequence dimension in your cube and input the details for each account on a separate page.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Timescales
The FV BiF assumes that the timescale is composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

Error message
If the timescale contains gaps between the periods or overlapping period, you will see the error message: @FV invalid timescale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

Warning message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 lunar or calendar months. The length in days of all periods is between 89 and 92 calendar quarters. The length in days of all periods is between 120 and 123 (3 periods each year). The length in days of all periods is 365 or 366.

User Guide 405

Chapter 12: Built in Functions (BiFs) If none of the tests are true, the warning message @FV time scale {time scale D-List name} has periods of unequal lengths is displayed. The calculations are performed exactly the same, whether the message is there or not.

@Grow
Grow=@Grow(Base;%Growth Rate;Growth Type;SwitchOver) Input/Output Parameter
Base Input D-List Item D-List Item L C Switchover Input Param

Description
The base data in period 1. Percentage to grow by in each period. Linear growth rate. Compound growth rate (default if blank). The period containing the switchover date is defined as the first future period.

% Growth Rate Input Growth Type Input Param

None 19970501 DList Today 5 Grow Result BiF D-List Item

treat all periods as historic May1, 1997 use switchover date in timescale D-List use today's date use May

How Grow works

The Grow BiF grows a base figure by a specified percentage each period. It can be compound or linear. For example, Grow result=@Grow(Base;{%Growth Rate};C;4) gives a compound growth rate starting from a switchover date in period 4 (April). Grow result=@Grow(Base;{%Growth Rate};L;4) gives a linear growth rate. The periodic increase is calculated as a percentage of the base figure in period 4 (April).

Formula for Grow

Prior to the period containing the switchover date:

406 Analyst

Chapter 12: Built in Functions (BiFs) Grow_result=Base In the period containing the switchover date, for both linear and compound growth rates:
Grow_result i = Base i* [(100+ratei )/100]

Thereafter, if the growth type is compound, the increase each period is calculated based on the previous result:
Grow_result n= Grow_resultn-1 + [Grow_resultn-1 * (raten-1 / 100] )

Jan
Base Rate Grow 800 10% 800

Feb
800 10% 800

Mar
900 10% 900

Apr
1000 10% 1100

May

Jun

Jul

Aug

Sep

10% 1210

10% 1331

10% 1464

10% 1611

10% 1772

If the growth type is linear, the increase each period is calculated as a percentage of the base figure.
Grow_result n= Grow_resultn-1 + [Base i * (raten-1 / 100)]

Jan
Base Rate Grow 800 10% 800

Feb
800 10% 800

Mar
900 10% 900

Apr
1000 10% 1100

May

Jun

Jul

Aug

Sep

10% 1200

10% 1300

10% 1400

10% 1500

10% 1600

Where n = periods after switchover date, rate=% growth rate, and Base is the base figure in the period containing the switchover date.

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display the groe" lw result. 4. Click Change item attributes. 5. Click BiF. 6. Select Grow from the Function Name list. 7. Click Next. 8. Double-click the parameters in the BiF Function Wizard.

User Guide 407

Chapter 12: Built in Functions (BiFs) 9. In the Growth Type parameter, enter L for linear growth, C for compound growth. If left blank, it will default to compound growth. 10. Enter the SwitchOver parameter. For generic monthly timescale D-Lists only, type the period number (for example, 4 for April) . For timescale D-Lists defined by dates, type the switchover date (for example, 19980401 to use April 1st, 1998 or Today to use todays date). Alternatively type Dlist to use the switchover date contained in the timescale D-List. 11. Select Finish. 12. Click Apply. 13. Save the D-List.

@ICF
Current=@ICF(Constant;Rate;APR?;Switchover) Input/Output
Constant Rate Input Input

Parameter
D-List Item D-List Item or Constant Leave blank R P PR

Description
The base value The discount rate (inflation rate)

APR

Input

annual % by default annual rate (rate = %/100) periodic % periodic rate The last historic period is that which contains the switchover date

Switchover

Input

None 19970501 DList

Treat all periods as historic May1, 1997 Use switchover date in timescale D-List Use today's date Use May

Today 5

408 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output
Current BiF Result

Parameter
D-List Item

Description
The inflated cashflow result.

How ICF works

ICF, the inflated cash flow function, calculates the amount of cash you must receive in a future period to compensate for inflation. For example, suppose the current year is 1999 and you need to know what income stream you need to receive in future years to be equivalent to an income stream of 1000 per annum in todays money. Current Cost = @ICF({Constant Dollars};Rate;R;20011231) uses an entered annual rate of 0.1 (=10%) and a switchover date of Dec 31st, 2001. Two years from now (two periods from the period containing the switchover date), the current cost equivalent would be 1210 at a discount rate of 0.1 (10%) per annum. Current = 1000 * (1+0.1) ^ 2 = 1210

1999
Current Cost Rate Constant 1000

2000
1000

2001
1000

2002
1000

2003
1000

2004
1000

0.10 826

0.10 909

0.10 1000

0.10 1100

0.10 1210

0.10 1331

If the APR? parameter is left blank, the rate is treated as an annual percentage. For example, Current Cost = @ICF({Constant Dollars};Rate; ;1) uses an entered annual percentage rate and a switchover date of January. The period number may only be used with a generic monthly timescale D-List.

Jan
Current Cost Rate Constant 1000 10 1000

Feb
1000 10 1007

Mar
1000 10 1015

Apr
1000 10 1023

May
1000 10 1032

Jun
1000 10 1040

Other valid examples include the following: Current value = @ICF(Constant;4.5;;Dlist) uses a constant annual percentage rate of 4.5% and looks in the timescale D-List for the switchover date. Current value = @ICF(Constant;1.2;P;19990301) uses a monthly periodic percentage rate of 1.2% ( =15.39% per annum) and March 1st, 1999 for the switchover date.

User Guide 409

Chapter 12: Built in Functions (BiFs)

Formula used by ICF

Current=1000*(1+0.1) ^2 =1210 Where r = discount rate expressed as a decimal fraction n = number of periods into the future There are four acceptable methods of entering the discount rate: Enter an annual percentage, an annual rate, a periodic percentage, and a periodic rate. The annual equivalent shows the periodic monthly rate 0.00797 (0.797% per month), which is equivalent to an annual rate of 10%.

Parameter

Meaning

Annual Equivalent
10 0.1 0.797 0.00797

Relationship

Leave blank R P PR

= annual % = annual rate = periodic % = periodic rate

% (default) R=%/100 P=PR*100 (1+PR)^12 = (1+R) for 12 periods

Set up the ICF Calculation Steps

1. Create a calculation D-List. Refer to the tables above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this example, Constant Dollars. 3. Click Change item attributes. 4. Click BiF. 5. Select ICF from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Specify APR In the APR box, you have several options: 410 Analyst Leave blank to default to an annual percentage. Type P for periodic percentage Type PR for periodic rate

Chapter 12: Built in Functions (BiFs) Type R for annual rate

9. Specify Switchover In the Use Switchover box, you have several options: Type Dlist to use the switchover date defined in the timescale D-List Type Today to use todays date Type a date (for example, 19990609) to specify a date Type a number (for example, 5) to specify a generic month Switchover parameters entered in the BiF formula will override the switchover date contained in the timescale D-List.

10. Click Finish. 11. Click Apply. 12. Save the D-List.

@IRR
IRR = @IRR(Values; Date Flag; Payment Date; Guess; Method) Definition
IRR means Internal Rate of Return and it is closely related to the NPV (Net Present Value) function. For any series of cashflows, the Internal Rate of Return is that rate for which NPV is equal to zero. In order to calculate IRR, the series of cashflows must contain at least one positive and one negative number.

Input/Output Parameter
Values Input D-List Item

Description
The series of cash values for which a rate is to be calculated. This must contain at least one negative and one positive number. Date of Payment: 1 = Start; 2 = Middle; 3 = End; 4 = User. Used to define when, during the period, the payment takes place. When date flag = 4, this date will be used. This field should be date formatted unless a generic monthly timescale is in use in which case a numeric input to this field is permitted. The numbers 1 to 30 may be used where 1 means the first and 30 means the last day of the month.

Date Flag

Input

D-List Item

Payment Date

Input

D-List Item

User Guide 411

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
Guess Method Input Input D-List Item D-List Item

Description
Defaults to zero. Input as a percentage. 1= Calculate looking forward to all future periods. 2=Calculate looking backwards at all past periods. IRR result is only shown in the periods where the method flag (1 or 2) is set. Usually, this would be a D-List item, but could be a constant in the formula. If it is a constant in the formula, the IRR result appears in all time periods. Unsolvable IRR calculations display as a zero, and show a warning flag. If no method is set at all, or is an invalid number in the method input, it defaults to showing IRR result in the first time period only, calculated by looking forward. The Internal Rate of Return. The rate of return yielded by the series of cashflows calculated as an annual percentage. Runs for 20 iterations and to an accuracy level of 0.001%

IRR

Output

D-List Item

How IRR works

IRR calculates the Internal Rate of Return for a series of cashflows on specified dates which need not be periodic. There must be at least one positive and one negative value in the series. All payments after the first, are discounted based on a 365 day year. Starting from the value input for Guess (which is zero by default) IRR is calculated using an iterative method. If, after 20 iterations, an accuracy level of 0.001% has not been achieved, then the rate is returned as zero and an error warning message is displayed. For a given series of cashflows there may be more than one solution or no solutions found for IRR.

Example
Project Evaluation. A machine is purchased on 12th October 2000 at a cost of 10000. Plans and budgets indicate that the purchase of the machine will be directly responsible for extra profits in subsequent years as follows: Year 2001 = 1000 Year 2002 = 2500 Year 2003 and following 4000. It is assumed that the extra profit is generated at the end of each year. The internal rate of return on the project is therefore calculated as follows:

412 Analyst

Chapter 12: Built in Functions (BiFs)

2000
Values (10000)

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
4000 3 - End

2005
4000 3 - End

2006
4000 3 - End

Date Flag 4 - User Payment Date Method Guess IRR 18.00% 12/10/00

However, suppose things do not go exactly according to plan. In 2004, extensive maintenance is required resulting in a cost of 1500 on 30th June, there is no profit generated that year, and profits for 2005 are reduced by 1000. The internal rate of return to the company is reduced as shown.

2000
Values Date Flag Payment Date Method Guess IRR 6.61% (10000) 4 - User 12/10/00

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
(1500) 2 - Mid

2005
3000 3 - End

2006
4000 3 - End

So far, we have used Method 1 only and calculated IRR for the whole sequence, returning a value in the first time period only. Where method 2 is used, the IRR calculated looks back and calculates for the preceding periods only. Thus we can calculate the IRR for part of the sequence only. Here we calculate the IRR for the cashflow sequence for each year.

2000
Values (10000)

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
4000 3 - End

2005
4000 3 - End

2006
4000 3 - End

Date Flag 4 - User

User Guide 413

Chapter 12: Built in Functions (BiFs)

2000
Payment Date Method Guess IRR 18.00% 12/10/00

2001

2002

2003

2004

2005

2006

(84.87%)

(41.10%)

(10.30%) 4.53%

12.89%

18.00%

A Mathematical Justification
The data below illustrates an investment of 10000, which produces a return of 11000 after one year.

2000
Values Date Flag Payment Date Method Guess IRR 10.00% 1 (10000) 3 - End

2001
11000 3 - End

2002

2003

2004

2005

2006

3 - End

3 - End

3 - End

3 - End

3 - End

IRR is a percentage rate per annum. Here we are looking at an investment which has increased by 10% in a year, as shown by the IRR calculation. The data below illustrates an investment of 10000, which produces a return of 11000 after one month. A generic months timescale is used here so the period is 365/12 days.

Jan
Values Date Flag Payment Date Method 1 (10000) 3 - End

Feb
11000 3 - End

Mar

Apr

May

Jun

Jul

3 - End

3 - End

3 - End

3 - End

3 - End

414 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Guess IRR 213.84%

Feb

Mar

Apr

May

Jun

Jul

IRR is a percentage rate per annum. Here we are looking at an investment which has increased by 10% in a month. Increasing a value by 10% multiplies it by 1.1. The interest will be applied 12 times in the course of a year. So 10% a month applied 12 times increases it by 1.1^12 = 3.1384, a percentage growth of 213. 84%.

Formula Used by IRR

IRR is the solution to
N

0=
i=1

P i (1 + IRR )
i(d365dl)

Where Pi is the Payment Value in th i the period di is the i th or last Payment date d1 is the date at which the IRR is being calculated so that di - d1 means the number of days forward from the day where IRR is being calculated. It is found by making repeated iterations starting from the value of Guess. If no solution has been found after 20 iterations, an error warning message will be displayed. If multiple solutions are detected, the solution nearest to Guess will be returned as a result and a calculation warning message will be displayed.

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List containing the items Values, Date Flag, Date, Method, Guess, and IRR. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item to which you want to calculate the IRR result. 4. Click Change item attributes. 5. Click BiF. 6. Select IRR from the Function Name list. 7. Click Next. 8. Enter the Date Flag parameter by selecting a Date Flag D-List item or typing a constant, which may be 1 - start of period, 2 - middle of period, 3 - end of period, or 4 - User defined date.

User Guide 415

Chapter 12: Built in Functions (BiFs) 9. Enter the Payment Date parameter by selecting a Payment Date D-List item. 10. Enter the Method parameter. If you select the Method D-List item, IRR will be calculated only in periods where a value of 1 or 2 is entered for Method. If there are no entries in the Method row at all in any slice, then IRR will be calculated in the first time period only, using Method 1. (Method 1 means look forward and calculate IRR based on all future values, Method 2 means look back and calculate based on all past values). Alternatively enter a constant of 1 or 2 here and IRR will be calculated in every period according to your chosen method. 11. Enter the Guess parameter by selecting a Guess D-List item. 12. Click Finish. 13. Format the Guess and the IRR items to a numeric format as desired. To display the results as percentages to 2 decimal places, go to the format field and click Change item attributes. 14. Select the numeric format, set the scaling factor to 0.01, the decimal places to 2, and type a % sign in both the negative and positive suffix boxes. 15. Click Apply. 16. Save and close the D-List.

Messages and input ranges Invalid Cashflow Sequences

IRR can only be calculated where there is at least one positive and one negative value in the cashflow sequence. If an attempt is made to calculate IRR for a series which does not qualify, the rate will return a value of zero. In the example given above, an attempt to calculate IRR for the Plan sequence from 2001 onwards will return a zero rate.

2000
Values Date Flag Payment Date Method Guess IRR 18.00% (10000) 4 - User 12/10/00

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
4000 3 - End

2005
4000 3 - End

2006
4000 3 - End

0.00%

(41.10%)

(10.30%)

4.53%

12.89%

18.00%

416 Analyst

Chapter 12: Built in Functions (BiFs)

Insoluble Inputs
For some valid cashflow sequences, no IRR can be found. In some cases, inserting a Guess value close to the answer you expect may prompt a solution. The yellow calculation warning box will appear and clicking on it will reveal this message: @IRR from guess xx in period yy of {slice name} cannot be solved with your inputs. Sometimes the solution is not fully converged after 20 iterations and a partially converged result will be returned. A warning message will be displayed, with the value of the error.

2000
Values (10000)

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
(3000) 3 - End

2005
4000 3 - End

2006
4000 3 - End

Date Flag 4 - User Payment Date Method Guess IRR 5.56% 12/10/00

(84.87%)

(41.10%)

(10.30%) (27.67)% (4.76)%

5.56%

Multiple Solutions
Sometimes a cashflow sequence gives rise to multiple possible solutions for IRR. When this happens, the value nearest to Guess will be returned as the result and a calculation warning will be displayed. The warning tells you that there is an alternative solution, and gives a value range for it.

2000
Values (10000)

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
(1500) 2 - Mid

2005
3000 3 - End

2006
4000 3 - End

Date Flag 4 - User Payment Date Method Guess IRR 6.61% 12/10/00

(84.87%)

(41.10%)

(10.30%)

(19.41)% (3.11)%

6.61%

User Guide 417

Chapter 12: Built in Functions (BiFs) To reveal the alternative solution, insert a guess at the value suggested.

2000
Values Date Flag (10000) 4 - User

2001
1000 3 - End

2002
2500 3 - End

2003
4000 3 - End

2004
(1500) 2 - Mid

2005
3000 3 - End

2006
4000 3 - End

Payment Date 12/10/00 Method Guess IRR 6.61% 1 2 2 2 2 (90.00) (84.87%) (41.10%) (10.30%) (87.68)% (3.11)% 6.61% 2 2

The alternative solution which fits this sequence is -87.68%. Now the error message alerts you to the fact that another solution between -20% and -10% exists.

User Defined Dates

If the date flag is set to 4, the user must define a date for that period in the Date row. The Date item in the calculation D-List is usually date formatted unless a monthly generic timescale is being used. If the payment date input falls outside the current period, the closest valid date will be used and one of the following messages will be displayed. Payment date is before the first day of periods {period-names} of slice {slice-name} Payment date is after the last day for periods {period-names} of slice {slice-name} Where {slice-name} is item-name1; item-name2; ...;, one name for each dimension other than time and the one holding the BiF formula. If a monthly generic timescale is used, and Date Flag is set to 4, a number between 1 and 30 should be input for date, where 1 means the first day of the month, and 30 means the last day of the month.

@Lag
Lag Result=@Lag(Periods;Pad;Inputs) Input/Output Parameter
Periods Input + 0 D-List Item

Description
set a lag of n periods (default=0) set a lag of n periods set a lag of variable number of periods according to what is contained in the D-List item.

418 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
Pad Input D-List Item or Constant

Description
If looking P periods back takes you outside the timescale, use the value in the padding for the current period. The series to be lagged (for example, invoiced amounts). The lag result (for example, cash payments made after a lag of n periods).

Input

Input

D-List Item

Lag Result

BiF Result

D-List Item

How Lag works

Lag calculates a result in one row by lagging an input from another row by a specified number of periods. The same calculation can also be used as a Lead function by expressing the number of periods as a negative integer. The result is the input lagged by P periods. P can be any integer. If P is not an integer, the first integer larger than P is used. When P is positive the result lags the input and the first P periods are taken from the item, Pad. When P is negative, the result leads the input and the last P periods are taken from the item, Pad. Pad may be another D-List item or a constant. Example: Result = @Lag(2;Pad;Inputs) uses a lag of 2 periods. The lagged result for June refers to the Inputs in April. The lagged results for April and May, the first two periods, try to look back to a time before the start of the financial year in April. Because this is outside the periods available, the item. Pad is used instead.

Jan
Input Pad Periods to lag Lag (Result) 1000 999 2 999

Feb
2000 888 2 888

Mar
2500 0 2 1000

Apr
2300 0 2 2000

May
3000 0 2 2500

Jun
1200 0 2 2300

If you set the Periods parameter as a negative integer, the result leads the input. For example, Result = @Lag(-3;Pad;Inputs) uses a lag of -3 periods which looks ahead 3 periods. For the last 3 periods, the inputs needed would come after the end of the timescale D-list, so the item Pad is used instead.

Jan
Input 1000

Feb
2000

Mar
2500

Apr
2300

May
3000

Jun
1200

User Guide 419

Chapter 12: Built in Functions (BiFs)

Jan
Pad Periods to lag Lag (Result) 0 (3) 2300

Feb
0 (3) 3000

Mar
0 (3) 1200

Apr
2000 (3) 2000

May
3000 (3) 3000

Jun
2500 (3) 2500

The parameter, Periods, does not need to be a constant. Apr result (2 lag) = Feb input For example, Result = @Lag(Periods;Padding;Input) uses a variable lag taken from the item Periods. The Padding is only used in a given period if the lag is such that the Inputs needed are outside the range of the timescale D-List. For example, Mar has a lag of 4, which is beyond the timescale, so the Pad value of 900 is used.

Jan
Input Pad Periods to lag Lag (Result) 1000 700 (1) 2000

Feb
2000 800 0 2000

Mar
3000 900 4 900

Apr
4000 1100 2 2000

May
5000 1300 3 2000

Jun
6000 1400 0 6000

Formula used by Lag

The result in period n lags the input by p periods. (Lag result, period n) = (Input, period n-p) If the lagged result requires inputs outside the timescale, use the values from Pad. (Lag result, period n) = (Pad, period n)

Steps to Use this BiF

1. Create a calculation D-List. Refer to the tables above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this example, Lag (Result). 3. Click Change item attributes. 4. Click BiF. 5. Select Lag from the Function Name list. 6. Click Next.

420 Analyst

Chapter 12: Built in Functions (BiFs) 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Last
Last Result = @Last (Input) Input/Output Parameter
Input Last Input Result D-List Item D-List Item

Description
The series of data on which Last operates. The most recent non-zero value in the series of data to a precision of 1x10^(-12).

How Last Works

Last looks back along the series of data in the input row and returns the most recent non-zero value. It calculates to a precision of 1x10^(-12), so that 0.000000000001 is the smallest number considered to be non-zero. It can be used to avoid re-keying of data over a long timescale where the input changes rarely over the periods.

Example 1 - Numeric Values

Suppose you have a timescale of 5 years in monthly periods and wish to input the following cashflow sequence: 200 per month for Year 1 300 per month for Year 2 400 per month for Year 3 500 per month for Year 4 600 per month for Year 5 Using the @Last BiF means that it is only necessary to input a cashflow value in the first period when a change occurs. In the cube below, you would need to enter only 5 numbers on the Values row as follows: 200 in Month 1, Year 1 300 in Month 1, Year 2 400 in Month 1, Year 3 500 in Month 1, Year 4 600 in Month 1, Year 5 User Guide 421

Chapter 12: Built in Functions (BiFs) The @Last BiF is used to produce the RESULT row and it returns the complete sequence of cashflows.

Month 11 Year 1
Input RESULT 0 200

Month 12 Year 1
0 200

Month 1 Year 2
300 300

Month 2 Year 2
0 300

Month 3 Year 3
0 300

Example 2 - Format D-Lists

Suppose January to April are actual periods and May onwards are forecast. Use of the @Last BiF means that you need only to input Actual in Period 1 and Forecast in Period 5 in the data input row. The @Last BiF is set in the Actual/Forecast Flag item which therefore returns the correct flag in each period.

Jan
Input Actual / Forecast Actual Actual

Feb

Mar

Apr

May
Forecast

Jun

Jul

Actual

Actual

Actual

Forecast

Forecast

Forecast

Formula Used by Last

The result in Period n shows the most recent non-zero value for the input. In @Last, the smallest number that is not zero is 0.000000000001, that is ten to the power minus twelve.

Steps to Use this BiF

1. Set up a D-Cube with a Timescale D-List and a Calculation D-List. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item to which you want to apply the BiF - in this example, Last. 4. Click Change item attributes. 5. Click BiF. 6. Select Last from the Function Name list. 7. Click Next. 8. Enter the Input parameter by selecting the D-List item that contains the inputs. 9. Click Finish.

422 Analyst

Chapter 12: Built in Functions (BiFs) 10. Set the Format column for the Result item to the same format as that used for the Input. Use either the same numeric format or format the items on the same D-List. 11. Click Apply. 12. Save and close the D-List. Using exactly the same principle, you can complete cells which are D-List formatted, where you require the same data to appear in a series of consecutive time periods.

@Lease
@Lease calculates a payment schedule for a lease, loan, mortgage, annuity, or savings account. It allows several lease contracts to be entered on a single page. The terms of each contract are entered in a single column. This is similar to @PMT, but allows different leases to be entered in different columns, as opposed to different pages. For each lease, the annual interest rate, term, present and future values are entered, and the constant payments are calculated as a result. Interest is entered per period, and can be constant or vary each period, and is compounded at the end of each period. Early redemption is allowed, expressed as a percentage of the opening balance. @Lease requires equal, consecutive periods. To enter a loan, you need to enter the advance amount, the duration of the loan - a positive integer equal to the number of periods over which the loan is due to be repaid, and the interest rate, expressed as a percentage rate per period. For example, a 1% interest rate per month would be entered as 1 across the entire rate row. This is equivalent to 12.68% per annum: 1.01^12 =1.1268. The advance amount and the residual value must be entered with opposite signs.

@Lease is one of a family of BiFs, that describe the behavior of a loan or annuity under the following specific conditions:
The timescale of the account is periodic and consecutive - that is to say, the account operates over a certain number of equal consecutive periods. Payments are made to or from the account, one at the beginning or end of each period as specified by the user. Early redemptions of accounts may be made either at a constant percentage each period or at a user specified percentage in any period. The projected residual value is also reduced by the redemption percentage. Further advances may be made in any period. These may have a specified residual value at the end of the account. Interest is defined as a rate per period which may be variable. Interest must be compounded at the end of each period. Multiple accounts may be input across any timescale slice - the BiF will calculate each account separately and return an aggregated output.

User Guide 423

Chapter 12: Built in Functions (BiFs)

Under these circumstances:

PV is the present value or start amount of the account. FV is the residual value of the account. Nper is the number of periods over which the account is calculated. Rate is the interest rate expressed as a percentage rate per period. PMT is the constant payment which would need to be applied to the account each period if there were no rate changes, further advances or redemptions and interest continued to be compounded in every period.

General Comments about @Lease

@Lease allows a series of accounts to be scheduled along a timescale. Each account must have a specified start and end value and run for a specified number of periods. Interest and redemption rates may be specified either as constant, in which case the rate in the start period will be applied for the duration of the account, or as variable, in which case the user must input a rate for every period in which the account is active.

Behavior of Interest
Interest is expressed as a rate per period. In common with other BiFs in this family, the timescale must consist of equal consecutive periods - see timescales (p. 426) below. However variable interest rates are allowed with this BiF.

Purpose and Use of the Lease Calculation

The BiF is designed to assist users with calculating the likely payments relating to loan contracts for budgeting purposes and has not been written to comply with any specific Consumer Credit legislation in any country.

D-List Item
Advance Amount PV

Type
Input

Comments
The payment to or from the account at the start of the calculation. Any further amount advanced in subsequent periods can be entered or left zero if no further advances occur.

Residual Amount FV Nper

Input

The payment to or from account at the end of the calculation. Would be zero for a loan which repays completely. The number of periods the account is to run.

Input

424 Analyst

Chapter 12: Built in Functions (BiFs)

D-List Item
Interest Method

Type
Input

Comments
1 = Constant, the default 2 = Variable It may be helpful to format this item on a D-List consisting of the two items Constant and Variable whose IID numbers are 1 and 2 respectively.

Redeem Method

Input

1 = Constant, the default 2 = Variable It may be helpful to format this item on a D-List consisting of the two items Constant and Variable whose IID numbers are 1 and 2 respectively.

When to Pay

Input 0 or 1 only

0, or any value other than 1, means the payment to the account is made at the end of the period. This is the default. 1 means the payment to the account is made at the start of the period.

Interest Rate Redemption Rate

Input Input

Interpreted as a percentage but must be the rate per period. Interpreted as a percentage but must be the rate per period.

Opening Value Output

The opening balance of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period. The BiF returns here the opening balance of the account adjusted for redemptions and further advances. Should be set as a time average, first period. The single payment to the account this period. This payment consists of an interest element and a capital element. If Type = 0 will equal Adjusted Opening * Rate per Period/100. If Type = 1 will equal (Adjusted Opening + Payment) * Rate per Period/100.

Adjusted Opening

Output

Payment

Output

Interest

Output

Redemptions

Output

The amount of the account paid off early Calculated by: In Period 1: Advance Amount* Redemption Rate /100. In subsequent periods: (Opening Value)* Redemption Rate /100.

User Guide 425

Chapter 12: Built in Functions (BiFs)

D-List Item
Residual Paid Off

Type
Output

Comments
Will be non-zero only in the last period of the account when it represents the residual value of the loan being repaid. It is equal to FV from the first period adjusted by any redemptions during the life of the loan.

Capital Paid Periods Remaining

Output Output

The amount of capital paid off in the period. Optional Item Will be Nper in the first calculation period and will reduce by 1 in each subsequent period. Optional Item FV from the first period adjusted by redemptions during the life of the loan to date.

Calc Residual Output

Closing Value Result

The closing balance of the account. Should be set as a time average, last period.

How @Lease Works

@Lease allows an account to be scheduled along a timescale representing the life of the loan. The timescale must consist of equal consecutive periods and one single payment must be made to the loan account in each period, either at the beginning or end of the period set by the when to pay variable. In the following sections, each of the different options is explored separately and the effects of further advances and early repayments are explained. Using various combinations of these features will afford considerable flexibility in budgeting lease payments.

Timescales
The timescale must consist of equal consecutive periods. However, some tolerance is allowed for common timescales consisting of all months, all quarters, all half years or all years. Insofar as the calculations are concerned, these are treated as being equal, even though their length may vary by a day or two. An error warning message will be displayed if the timescale used does not fulfil these criteria. If any one of these tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 (lunar or calendar month). The length in days of all periods is between 89 and 92 (calendar quarters). The length in days of all periods is between 120 and 123 (3 periods per year).

426 Analyst

Chapter 12: Built in Functions (BiFs) The length in days of all periods is between 180 and 185 (half years). The length in days of all periods is 365 or 366 (years).

A timescale of generic months is acceptable as this is treated as 12 equal consecutive periods of 30. 44 days.

Basic Loan Definition

In order to define an account to be calculated by @Lease, the following inputs must be made in the period in which the loan is to start. All other settings are optional and affect the way the account will behave. Advance Amount The start amount of the loan. Can be zero. If an advance has a residual amount, ensure that the advance and the residual have opposite signs. Residual Amount The amount left to pay at the end of the account can be zero. If an advance has a residual amount ensure that the advance and the residual have opposite signs. Nper Rate The number of periods the account is to run. Must be a positive integer. Must be the percentage rate per period. This will be applied for the duration of the account provided that Interest Method has been left at the default setting of Constant. If not, a rate must be input for every period in which the account is active.

Signs for Input Variables and Results

In order to obtain the correct results, it is necessary to observe a consistent convention regarding whether the input variables are positive or negative. In general, cashflows which increase the absolute value of an account (that is, increase the balance of a savings account or bring an overdrawn account such as a loan nearer to zero) will be positive. Cashflows which decrease the absolute value of an account will be negative. Advance Amount and Residual Value should be regarded as flows to or from the account rather than balances of the account. When this convention is followed, a positive interest rate will have the effect of increasing the balance on a savings account and making a loan further overdrawn so that the borrower has an increased amount to repay.

User Guide 427

Chapter 12: Built in Functions (BiFs)

Advance Amount Residual Value

Savings Account With opening deposit Regular savings Final end balance re-paid to investor Annuity With initial deposit from investor Regular payments from the account to the investor Any final balance paid back to investor Loan Initial amount paid to borrower Regular payments from borrower to loan account Any residual balance to be paid by borrower Negative Positive Positive Negative Positive Negative

Example 1 - A Straightforward Loan Series with Multiple Accounts per Timescale Slice Advance 1
A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. Advance Amount, Residual Value, Nper and Rate are input in the period where the account starts. Interest Method, Redemption Method and When to Pay are set to their default values. The Residual Value is deducted from the account in the final period - see the Residual Paid Off row, so the Closing Value of the account is zero.

Advance 2
A loan of 150000 over 4 months from June at a rate of 2% per month for the first 1 month and 1. 5% per month for the other 3 months with interest compounded monthly. The residual value will be 10000. Payments are made at the start of each month. This new account entered on its own would appear as follows:

Jan - May
Advance Amount Residual value 428 Analyst

Jun
(150000) 10000

Jul

Aug

Sep

Chapter 12: Built in Functions (BiFs)

Jan - May
No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Jun
4 1 Start 2.00% 0.00% 2 Variable

Jul

Aug

Sep

1.50% 0.00%

1.50% 0.00%

1.50% 0.00%

(150000) (150000) (2275) 36242

(116033) (116033) (1200) 36020

(81213) (81213) (678) 36020

(45872) (45872) (148) 36020

33697

34819

35342

35872 10000

(116033) 4 10000

(81213) 3 10000

(45872) 2 10000

0 1 10000

However, Lease Variable allows the user to combine the accounts on the same page, giving:

Jan Feb
Advance Amount Residual value No of Periods When To Pay (100000) 15000 6

Mar

Apr

May

Jun
(150000) 10000 4 1 Start

Jul

Aug

Sep

User Guide 429

Chapter 12: Built in Functions (BiFs)

Jan Feb
Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (86183) 6 15000 13817 (100000) (100000) (1000) 1.00% 0.00% 1 Constant

Mar

Apr

May

Jun
2.00% 0.00% 2 Variable

Jul
1.50% 0.00%

Aug
1.50% 0.00%

Sep
1.50% 0.00%

(86183) (72229) (58134) (193899) (145554) (86183) (72229) (58134) (193899) (145554) (862) (722) (581) (2714) (1495)

(81213) (45872) (81213) (45872) (678) (148)

14817

14817

14817

14817

51059

50836

36020

36020

13955

14094

14235

48345 15000

49341

35342

35872 10000

(72229) (58134) (43899) (145554) (81213) 5 15000 4 15000 3 15000 4 25000 3 25000

(45872) 0 2 10000 1 10000

Each account is calculated independently and the results are aggregated. Payments on the first account remain at 14817 for the duration of the account because the interest rate is defined as constant. The changed rates from June onwards are applied only to the second account. Note: The Periods Remaining figure displays the periods remaining until the latest account runs off.

Resolve Conflicts when Defining Multiple Accounts.

Sometimes a sequence D-List will still have to be used to define a series of accounts across a timescale. This will be necessary when: Accounts starting in the same period have different interest rates, run for a different number of periods or have different When to Pay values.

430 Analyst

Chapter 12: Built in Functions (BiFs) An account with variable interest or redemption rates has been defined earlier in the timescale and in a later period, you wish to define a new account with different interest or redemption rates.

Example 2 - Multiple Accounts with Conflicting Definitions

The following accounts cannot be defined together on a single timescale slice. Instead use a sequence D-List with a total to aggregate them.

The First Account

A loan of 150000 over 4 months, starting in June at a rate of 2% per month for the first month, and 1.5% per month for the other 3 months, with interest compounded monthly. The residual value will be 10000. Payments are made at the start of each month - shown in the second account in example 2 below.

Jan - May
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off

Jun
(150000) 10000 4 1 Start 2.00% 0.00% 2 Variable

Jul

Aug

Sep

1.50% 0.00%

1.50% 0.00%

1.50% 0.00%

(150000) (150000) (2275) 36242

(116033) (116033) (1200) 36020

(81213) (81213) (678) 36020

(45872) (45872) (148) 36020

33697

34819

35342

35872 10000

User Guide 431

Chapter 12: Built in Functions (BiFs)

Jan - May
Closing Value Periods Remaining Calc Residual

Jun
(116033) 4 10000

Jul
(81213) 3 10000

Aug
(45872) 2 10000

Sep
0 1 10000

The Second Account

A loan of 150000 over 4 months, starting in July at a rate of 2% per month for the first 1 month, and 1.5% per month for the other 3 months, with interest compounded monthly. The residual value will be 10000. Payments are made at the start of each month. In July, a rate of 1.5% has already been entered, as this is needed for the first account. The second account must therefore be defined on a separate page of the D-Cube, and the results must be aggregated using a sequence D-List. The following example shows defining the second account:

Jan - Jun Jul

Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions (150000) (150000) (2275) 36242 (150000) 10000 4 1 Start 2.00% 0.00% 2 Variable

Aug

Sep

Oct

1.50% 0.00%

1.50% 0.00%

1.50% 0.00%

(116033) (116033) (1200) 36020

(81213) (81213) (678) 36020

(45872) (45872) (148) 36020

432 Analyst

Chapter 12: Built in Functions (BiFs)

Jan - Jun Jul

Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (116033) 4 10000 33697

Aug
34819

Sep
35342

Oct
35872 10000

(81213) 3 10000

(45872) 2 10000

0 1 10000

The next example shows the aggregate page:

Apr - Jun May

Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid 33697 2.00% 0.00%

Jul

Aug

Sep

Oct

Nov

(150000) (150000) 10000 4 10000 4

3.50% 0.00%

3.00% 0.00%

3.00% 0.00%

3.00% 0.00%

3.00% 0.00%

(150000) (266033) (197246) (127085) (45872) 0 (150000) (266033) (197246) (127085) (45872) 0 (2275) 36242 (3475) 72262 (1878) 72039 (826) 72039 (148) 36020 0 0

68787

70161

71213

35872

User Guide 433

Chapter 12: Built in Functions (BiFs)

Apr - Jun May

Residual Paid Off Closing Value Periods Remaining Calc Residual

Jul

Aug

Sep

Oct

Nov

10000 (116033) (197246) (127085) (45872) 4 10000 7 20000 5 20000 3 20000

10000 0 1 10000

0 0 0 0

The rows that schedule the account, Opening Value to Closing value, return valid figures on the aggregate page. However the figures for Interest Rate, Redemption Rate, and Periods Remaining are simple totals of the figures for each of the two accounts, and are therefore meaningless. Definitions such as When to Pay, Interest Method and Redemption Method, that are made by means of format D-Lists do not appear on the aggregate page where the Calc.Option for those items is set to Force To Zero in the D-List.

Further Advances
@Lease may also be used to define a further advance to an existing account. In this case, the details of the further advance should be entered in the period where it is to take place. The value entered for Nper should be the same as the Periods Remaining figure for the original advance. The settings for Interest Method and Redeem Method should be the same as for the original advance. If Interest Method is set to Constant, the same rate as that for the original advance must be input. If Interest Method is set to variable, you will already have input your interest rate for all periods of the account.

Example 3 - A Further Advance

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month.

Jan
Advance Amount Residual value No of Periods When To Pay Rate

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

434 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr

May

Jun

Jul

1 Constant

(100000) (100000) (1000) 14817

(86183) (86183) (862) 14817

(72229) (72229) (722) 14817

(58134) (58134) (581) 14817

(43899) (43899) (439) 14817

(29521) (29521) (295) 14817

13817

13955

14.094

14235

14378

14521 15000

(86183) 6 15000

(72229) 5 15000

(58134) 4 15000

(43899) 3 15000

(29521) 2 15000

0 1 15000

In month 3, a further advance of 10000 is made with a residual value of 2000. Note: The signs of the input variables have start values input as negative numbers - paid from the account to the borrower, and the residual values are positive - paid from the borrower to the account.

Jan
Advance Amount Residual value No of Periods When To Pay Rate

Feb
(100000)

Mar

Apr
(10000)

May

Jun

Jul

15000 6

2000 4

1.00%

1.00%

User Guide 435

Chapter 12: Built in Functions (BiFs)

Jan
Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr

May

Jun

Jul

1 Constant

1 Constant

(100000) (100000)

(86183) (86183)

(82229) (82229)

(66164) (66164)

(49939) (49939)

(33551) (33551)

(1000)

(862)

(822)

(662)

(499)

(336)

14817

14817

16887

16887

16887

16887

13817

13955

16065

16225

16387

16551 17000

(86183) 6

(72229) 5

(66164) 4

(49939) 3

(33551) 2 1

15000

15000

17000

17000

17000

17000

From month three onwards, the payment for the further advance is added to the existing payment of 14817, making a new month payment of 16887. The residual value increases from 15000 to 17000 to reflect the residual from the further advance.

Redemptions
Early redemptions are input as percentages. Where a residual value has been input for an account, it is assumed that this will reduce by the same percentage. The payment to the account will be decreased by the redemption percentage automatically. Both advances and redemptions are assumed to occur at the start of a period. The When to Pay flag only affects the original advance and the regular repayments.

436 Analyst

Chapter 12: Built in Functions (BiFs) If a loan has When to Pay set to 1 - payments at the start of each period, no early redemptions are allowed in the final period. Redemptions may either be specified as a set percentage in each period of the account, which is done by setting Redeem Method to Constant and specifying the percentage in the first period of the account, or as variable with the percentage input for each period applied top the account. Note: Take care with multiple accounts defined across a timescale where you are using a mixture of Constant and Variable in your definitions. Remember that the interest rate and redemption rate you input for any period will be applied in that period to all active accounts for which you have defined Interest Method or Redeem Method as Variable. For information about resolving conflicts when defining multiple accounts, see "Resolve Conflicts when Defining Multiple Accounts." (p. 430).

Example 4 - An Early Redemption using the Constant setting

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. In month 3, a further advance of 10000 is made with a residual value of 2000. Early redemptions are made at 5% per period throughout the account.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment

Feb
(100000) 15000 6

Mar

Apr
(10000) 2000 4

May

Jun

Jul

1.00% 5.00% 1 Constant 1 Constant (100000) (95000) (81874) (77781)

1.00% 5.00% 1 Constant 1 Constant (75186) (71427) (57471) (41207) (26298) (54598) (39147) (24983)

(950)

(778)

(714)

(546)

(391)

(250)

14076

13372

14670

13937

13240

12578

User Guide 437

Chapter 12: Built in Functions (BiFs)

Jan
Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
5000 13126

Mar
4094 12594

Apr
3759 13956

May
2874 13391

Jun
2060 12848

Jul
1315 12328 12655

(81874) 6

(65186) 5

(57471) 4

(41207) (26298) 3 2 1

14250

13538

14761

14023

13321

12655

For the monthly redemptions of 5% to be applied to the further advance, as well as the original account, the further advance definition must be as shown above.

Example 5 - An Early Redemption using the Variable setting

A loan of 100000 over 6 months, at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. In month 3, a further advance of 10000 is made with a residual value of 2000. In month 4, an early redemption of 10% is made.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value

Feb
(100000) 15000 6

Mar

Apr
(10000) 2000 4

May

Jun

Jul

1.00%

1.00% 10.00%

1 Constant 2 Variable (100000) (86183)

1 Constant 2 Variable (82229) (66164) (44945) (30196)

438 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
(100000)

Mar
(86183)

Apr
(82229)

May

Jun

Jul

(59548) (44945) (30196)

(1000)

(862)

(822)

(595)

(449)

(302)

14817

14817

16887

15198 6616

15198

15198

13817

13955

16065

14603

14749

14896 15300

(86183) 6

(72229) 5

(66164) 4

(44945) (30196) 3 2 1

15000

15000

17000

15300

15300

15300

The redemption of 10% means that the borrower is required to make a payment of 6616 to the account in May. The residual value of the account is reduced by 10% from 17000 to 15300. The monthly payment is reduced by 10% from 16887 to 15198. The Capital Paid row indicates only the capital element of the regular payment to the account - it does not include the redemption.

Where a further advance and an early redemption take place in the same period, the further advance is considered to occur first.

Jan Feb
Advance Amount Residual value No of Periods When To Pay (100000) 15000 6

Mar

Apr
(10000) 2000 4

May

Jun

Jul

User Guide 439

Chapter 12: Built in Functions (BiFs)

Jan Feb
Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (86183) 6 13817 1 Constant 2 Variable (100000) (100000) 1.00%

Mar

Apr
1.00% 10.00% 1 Constant 2 Variable

May

Jun

Jul

(86183) (86183)

(82229) (74006)

(59548) (44945) (30196) (59548) (44945) (30196)

(1000)

(862)

(740)

(595)

(449)

(302)

14817

14817

15198 8223

15198

15198

15198

13955

14458

14603

14749

14896 15300

(72229) 5

(59548) 4

(44945) (30196) 3 2 1

15000

15000

15300

15300

15300

15300

The amount of the redemption is 8223, being the Opening Value of 72229 plus the further advance of 10000. The Adjusted Opening is the Opening Value adjusted for the further advance and the redemption.

The When to Pay? option

0 = Pay at end of period (the default) 1 = Pay at start of Period Setting this option allows the user to regulate when payments are made to the account. An account where payments occur at the start of the period will incur lower charges overall than one where payments are made at the end because the interest charges will be lower.

440 Analyst

Chapter 12: Built in Functions (BiFs) It might be helpful to format this item on a D-List consisting of a single item named Start with an IID of 1. An entry should only be made for this option in the first period of the loan - it cannot be varied during the life of the account. No entry must be made if you require payments at the end of each period. Both advances and redemptions are assumed to occur at the start of a period. The When to Pay flag only affects the original advance and the regular repayments.

Example 6 - A Loan with payments at the start of each period

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the start of each month. In month 3 a further advance of 10000 is made with a residual value of 2000. In month 4 an early redemption of 10% is made. This is example 5 with When to Pay set to 1.

Jan Feb
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Interest Method Redeem Method Opening Value Adjusted Opening Interest This Period Payment 1 Constant 2 Variable (100000) (100000) (100000) 15000 6 1 Start 1.00%

Mar

Apr
(10000) 2000 4 1 Start 1.00%

May

Jun

Jul

10.00% 1 Constant 2 Variable (86183) (86183) (82229) (82229) (66164) (59548) (44945) (44945) (30196) (30196)

(853)

(715)

(655)

(445)

(299)

(151)

14670

14670

16720

15048

15048

15048

User Guide 441

Chapter 12: Built in Functions (BiFs)

Jan Feb
Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (86183) 6 13817

Mar

Apr

May
6616

Jun

Jul

13955

16065

14603

14749

14896 15300

(72229) 5

(66164) 4

(44945) 3

(30196) 2

0 1

15000

15000

17000

15300

15300

15300

Note: The When to Pay flag must be input as 1 in both the start period of the original advance, and the further advance. Otherwise the further advance will be considered as an account on which payments are made at the end of the period, and have its payments calculated accordingly. The monthly payments are less than those for example 5. The monthly interest is less each month than in example 5 because the payment is deducted from the opening balance before the interest for the month is calculated. Interest is still compounded (added to the account) at the end of each period.

Messages and input ranges Insoluble inputs

If your inputs present a case that can not be solved, this warning message appears in the calculation errors: @Lease in period {period-name} of slice {slice-name} can not be solved with your inputs, where {slice-name} = item-name1; item-name2; ... with one name for each dimension in the D-Cube, excluding the Time and the Lease dimensions.

TimeScales
The Lease BiF assumes that the timescale is a composed of contiguous periods with the same length. If the timescale used does not meet this criteria, either the following error message or warning message will appear in the calculation messages.

Error Message
If the timescale contains gaps between the periods or overlapping period, the following error message is displayed: @Lease invalid time scale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

442 Analyst

Chapter 12: Built in Functions (BiFs)

Warning Message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 (lunar or calendar month). The length in days of all periods is between 89 and 92 (calendar quarters). The length in days of all periods is between 120 and 123 (3 periods per year). The length in days of all periods is 365 or 366 (years).

Otherwise you see the warning message: @Lease time scale {time scale D-List name} has periods of unequal lengths. The calculations are performed exactly the same, whether the message is there or not.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Signs of Input Variables

A calculation warning is displayed where an account is defined with the Advance Amount and Residual Value having the same sign.

@LeaseVariable
@LeaseVariable calculates a payment schedule for a lease, loan, mortgage, annuity or savings account. For each lease, you can have further advances, early repayments, and interest rates can vary over time. The repayments are calculated at a constant amount per period unless you have taken out a further advance or made an early redemption. @LeaseVariable caters for instances like your mortgage where the monthly payments are set every January, but interest rates can vary from time to time. You can flag when you want the constant monthly payments to be recalculated. Key differences from @Lease are: @LeaseVariable requires one lease contract per page @LeaseVariable allows for further advances You can choose whether to compound the interest at the end of each period or to accrue interest and carry it forward. When changes in interest rates occur, you can choose whether to change the payments or keep them constant and accrue the interest.

To enter a loan, you need to enter the advance amount, the duration of the loan (a positive integer equal to the number of periods over which the loan is due to be repaid) and the interest rate, expressed as a percentage rate per period. For example, a 1% interest rate per month would be

User Guide 443

Chapter 12: Built in Functions (BiFs) entered as 1 across the entire rate row. This is equivalent to 12.68% per annum: 1.01^12 =1.1268. The advance amount and the residual value must be entered with opposite signs. @LeaseVariable is one of a family of BiFs that describe the behavior of a loan or annuity under the following specific conditions: The time scale of the account is periodic and consecutive, operating over a certain number of equal consecutive periods. Payments are made to or from the account, one at the beginning or end of each period as specified by the user.

You are allowed to peg the payments at a fixed level for a number of periods. This caters for loans such as mortgages, where monthly payments are fixed for a year, then subject to an annual review. You are accruing interest, so you do not pay more or less than you should. On the review date, the future monthly payments are recalculated. Everything else being equal, this new payment level is calculated to exactly pay off the loan and interest by the redemption date. If there are further changes in interest rates, these payments would change at the next annual review. If there are further advances or redemptions, the user may choose either to adjust the existing payment only by the amount required to take account of these capital changes, or to trigger a payment review on the whole account. Early redemptions of accounts may be made at a user specified percentage in any month. The projected residual value is also reduced by the redemption percentage. Further advances may be made in any period. These may have a specified residual value at the end of the account. Interest is defined as a rate per period that may be variable. Interest may be compounded at the end of a period, or accrued and carried forward at the users option.

Under these circumstances:

PV (p. 509) is the present value or start amount of the account. FV (p. 395) is the residual value of the account. Nper (p. 484) is the number of periods over which the account is calculated. Rate (p. 518) is the interest rate expressed as a percentage rate per period. PMT (p. 501) is the constant payment which would need to be applied to the account each period if there were no rate changes, further advances or redemptions and interest continued to be compounded in every period.

General Comments about LeaseVariable

LeaseVariable allows you to schedule an account along a constant periodic time scale but allows considerable flexibility in the behavior of the account. Only one account is allowed per time scale slice of the D-Cube, so a sequence type D-List must be included if more than one account is to be calculated. Each account may, however be considered either as a single contract or as the total of a number of contracts issued which all start at the same time, have the same definition and behave in the same way in each subsequent period.

444 Analyst

Chapter 12: Built in Functions (BiFs)

Behavior of Interest
Interest is expressed as a rate per period. In common with other built in functions in this family, the time scale must consist of equal consecutive periods. For information about time scales, see "Timescales" (p. 447). However variable interest rates are allowed with this BiF. It is not mandatory to compound interest in every period. You could, for example, have monthly payments to the account with interest charged quarterly. In periods where interest is compounded, it is compounded at the end of the period. Appendix 1 gives details on converting annual rates to rates per period for various loan types. Important! This BiF is designed to assist users with calculating the likely payments relating to loan contracts for budgeting purposes and has not been written to comply with any specific consumer credit legislation in any country.

Variables D-List Item

Advance Amount

Type
Input

Comments
The payment to or from the account at the start of the calculation. Any further amount advanced in subsequent periods can be zero.

Residual Value

Input

The payment to or from account at the end of the calculation. Would be zero for a loan that repays completely.

Nper When to Pay

Input

The number of periods the account is to run.

Input 0 0, or any value other than 1, means the payment to the account or 1 only is made at the end of the period. This is the default 1 means the payment to the account is made at the start of the period.

Rate Redemption Rate Compound

Input Input Input

Interpreted as a percentage but must be the rate per period. Interpreted as a percentage but must be the rate per period. Indicate whether or not to compound interest this period. No = 1 Yes = 2 Default is Yes It may be helpful to format this item on a D-List consisting of the two items NO and YES, whose IID numbers are 1 and 2 respectively.

User Guide 445

Chapter 12: Built in Functions (BiFs)

D-List Item
Recalculate

Type
Input

Comments
Indicate whether or not to recalculate payments to take account of interest rate changes this period. No = 1 Yes = 2 Default is Yes It may be helpful to format this item on a D-List consisting of the two items NO and YES, whose IID numbers are 1 and 2 respectively.

Calc Payment

Output

The repayment on each further advance. This is calculated separately based on the current interest rate and the number of periods the original loan has still to run.

Opening Value

Output

The opening balance of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period.

Adjusted Opening

Output

The BiF returns here the opening balance of the account adjusted for redemptions and further advances. Should be set as a time average, first period.

Interest this period

Output

If Type = 0 will equal Adjusted Opening * Rate per Period/100. If Type = 1 will equal (Adjusted Opening + Payment) * Rate per Period/100.

Accrued Interest

Output

Any interest calculated in previous periods not yet applied to the account. The single payment to the account this period This payment consists of an interest element and a capital element.

Payment

Output

Redemptions

Output

The amount of the account paid off early Where there is a further advance in the same period, this is considered to be made before the redemption amount is calculated by: In Period 1: Advance Amount* Redemption Rate /100 In subsequent periods: (Opening Value + Advance Amount)*Redemption Rate /100.

446 Analyst

Chapter 12: Built in Functions (BiFs)

D-List Item
Residual Paid Off

Type
Output

Comments
Will be non zero only in the last period of the account when it represents the residual value of the loan being repaid. It is equal to FV from the first period adjusted by any redemptions during the life of the loan.

Capital Paid Periods Remaining

Output Output

The amount of capital paid off in the period. Optional Item Will be Nper in the first calculation period and will reduce by 1 in each subsequent period.

Calc Residual

Output

Optional Item FV from the first period adjusted by redemptions during the life of the loan to date.

Closing Value

Result

The closing balance of the account should be set as a time average, last period.

How @LeaseVariable Works

@LeaseVariable allows an account to be scheduled along a time scale representing the life of the loan. The time scale must consist of equal consecutive periods and one single payment must be made to the loan account in each period, either at the beginning or end of the period set by the When to Pay variable. It is not necessary to compound the interest in each period. In the following sections, each of the different options is explored separately and the effects of further advances and early repayments are explained. Using various combinations of these features allows considerable flexibility in budgeting lease payments.

Timescales
The timescale must consist of equal consecutive periods. However, some tolerance is allowed for common timescales consisting of all months, all quarters, all half years, or all years. Insofar as the calculations are concerned, these are treated as being equal, even though their length may vary by a day or two. A warning message will be displayed if the timescale used does not fulfill these criteria.

If any one of these tests is true, no message is issued:

All the periods have exactly the same length. The length in days of all periods is between 28 and 31 (lunar or calendar month). The length in days of all periods is between 89 and 92 (calendar quarters). The length in days of all periods is between 120 and 123 (3 periods per year).

User Guide 447

Chapter 12: Built in Functions (BiFs) The length in days of all periods is between 180 and 185 (half years). The length in days of all periods is 365 or 366 (years).

A timescale of generic months is acceptable because this is treated as 12 equal consecutive periods of 30.44 days.

Totals and Timescales

This BiF will only calculate results from the inputs in one time period for any slice of a D-Cube. Therefore, to make calculations for a series of accounts, it is necessary to include a sequence type D-List and enter the details for each account on a separate page. Only the payment figure, PMT is meaningful as a total figure either across time periods or a series of accounts. However, the BiF can return Opening Balance, Closing Balance, Interest Paid and Payments as outputs. These figures make valid totals, provided the correct time average settings have been made.

Basic Loan Definition

In order to define an account to be calculated by @LeaseVariable, the following inputs must be made in the period in which the loan is to start. All other settings are optional and affect the way the account will behave. Advance Amount The start amount of the loan Can be zero If an advance has a residual value, ensure that the advance and the residual have opposite signs. Residual Value The amount left to pay at the end of the account Can be zero If an advance has a residual value, ensure that the advance and the residual have opposite signs. Nper The number of periods the account is to run Must be a positive integer. Additionally, for every period in which the account is active you must input a Rate, otherwise the rate for that period will be treated as zero. Tip: To input a rate across all periods, set the timescale D-List to be the column and input. For example, enter 5> for a rate of 5% per period.

Signs for Input Variables and Results

In order to obtain the correct results, it is necessary to observe a consistent convention regarding whether the input variables are positive or negative. In general, cashflows that increase the absolute value of an account, that is, increase the balance of a savings account or bring an overdrawn account such as a loan nearer to zero, will be positive.

448 Analyst

Chapter 12: Built in Functions (BiFs) Cashflows that decrease the absolute value of an account will be negative. Advance Amount and Residual Value should be regarded as flows to or from the account rather than balances of the account. When this convention is followed, a positive interest rate will have the effect of increasing the balance on a savings account and making a loan further overdrawn so that the borrower has an increased amount to repay.

Advance Amount
Savings Account With opening deposit Regular savings Final end balance re-paid to investor Annuity With initial deposit from investor Regular payments from the account to the investor Any final balance paid back to investor Loan Initial amount paid to borrower Regular payments from borrower to loan account Any residual balance to be paid by borrower Negative Positive Positive

Residual Value
Negative

Negative

Positive

Example 1 A Straightforward Loan

A loan of 100,000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15,000. Payments are made at the end of each month.

Jan
Advance Amount Residual Value No of Periods When To Pay Rate Redemption Rate

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

User Guide 449

Chapter 12: Built in Functions (BiFs)

Jan
Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
2 Yes 2 Yes 14817

Mar
2 Yes 2 Yes

Apr
2 Yes 2 Yes

May
2 Yes 2 Yes

Jun
2 Yes 2 Yes

Jul
2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(72229) (72229) (722) 0 14817

(58134) (58134) (581) 0 14817

(43899) (43899) (439) 0 14817

(29521) (29521) (295) 0 14817

13817

13955

14094

14235

14378

14521 15000

(86183) 6 15000

(72229) 5 15000

(58134) 4 15000

(43899) 3 15000

(29521) 2 15000

0 1 15000

Advance Amount, Residual Value and Nper are entered in the period where the account starts. Rate must be input in every period. When to Pay, Recalculate? and Compound? are set to their default values. The Residual Value is deducted from the account in the final period see the Residual Paid Off row, so the Closing Value of the account is zero.

Further Advances
Although @LeaseVariable only deals with one account per timescale slice, it is possible to define capital additions to the account. However, these must run to the same expiry date as the existing account. When a further advance is entered, the payment required for the further advance is added to the existing payment for the account automatically. Further advances input to time periods after the last period of the account will be ignored.

450 Analyst

Chapter 12: Built in Functions (BiFs) Note: The Recalculate? option, affects how the existing payment is calculated, not the payment for the further advance. It is therefore not mandatory to set Recalculate? to Yes in a period where a further advance is made. If a loan has When to Pay set to 1 payments at the start of each period, no further advances are allowed in the final period.

Example 2 A Further Advance

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. In month 3 a further advance of 10000 is made with a residual value of 2000. Note: The signs of the input variables have start values input as negative numbers - paid from the account to the borrower, and the residual values are positive - paid from the borrower to the account.

Jan Feb
Advance Amount Residual Value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions 2 Yes 2 Yes 14817 1.00% (100000) 15000 6

Mar

Apr
(10000) 2000

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

2 Yes 2 Yes

2 Yes 2 Yes 2070 (72229) (82229) (822) 0 16887

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(66164) (66164) (662) 0 16887

(49939) (49939) (499) 0 16887

(33551) (33551) (336) 0 16887

User Guide 451

Chapter 12: Built in Functions (BiFs)

Jan Feb
Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (86183) 6 15000 13817

Mar
13955

Apr
16065

May
16225

Jun
16387

Jul
16551 17000

(72229) 5 15000

(66164) 4 17000

(49939) 3 17000

(33551) 2 17000

0 1 17000

No value is input for Nper in the period of the further advance the further advance must run for the remaining period of the existing account. The Calc Payment of 2070 in April is the payment required for the further advance element only. From month 3 onwards this is added to the existing payment of 14817, making a new month payment of 16887. The residual value increases from 15000 to 17000 to reflect the residual from the further advance.

Redemptions
Early redemptions are input as percentages. Where a residual value has been input for an account it is assumed that this will reduce by the same percentage. The payment to the account will be decreased by the redemption percentage automatically. Note: The Recalculate? option affects how the existing payment is calculated. This payment will then be adjusted by the redemption percentage. It is therefore not mandatory to set Recalculate? to Yes in a period where a redemption is made. Both advances and redemptions are assumed to occur at the start of a period. The When to Pay flag only affects the original advance and the regular repayments. If a loan has When to Pay set to 1, payments at the start of each period, no early redemptions are allowed in the final period.

Example 3 An Early Redemption

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. In month 3 a further advance of 10000 is made with a residual value of 2000. In month 4 an early redemption of 10% is made.

452 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Advance Amount Residual Value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
(100000) 15000 6

Mar

Apr
(10000) 2000

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

2 Yes 2 Yes 14817

2 Yes 2 Yes

2 Yes 2 Yes 2070 (72229) (82229) (822) 0 16887

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(66164) (66164) (662) 0 16887

(49939) (49939) (499) 0 16887

(33551) (33551) (336) 0 16887

13817

13955

16065

16225

16387

16551 17000

(86183) 6 15000

(72229) 5 15000

(66164) 4 17000

(49939) 3 17000

(33551) 2 17000

0 1 17000

The redemption of 10% means that the borrower is required to make a payment of 6616 to the account in May. The residual value of the account is reduced by 10% from 17000 to 15300.

User Guide 453

Chapter 12: Built in Functions (BiFs) The monthly payment is reduced by 10% from 16887 to 15198. The Capital Paid row indicates only the capital element of the regular payment to the account, it does not include the redemption.

Where a further advance and an early redemption take place in the same period, the further advance is considered to occur first.

Jan
Advance Amount Residual Value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining

Feb
(100000) 15000 6

Mar

Apr
(10000) 2000

May

Jun

Jul

1.00%

1.00%

1.00% 10.00%

1.00%

1.00%

1.00%

2 Yes 2 Yes 14817

2 Yes 2 Yes

2 Yes 2 Yes 2070 (72229) (74006) (740) 0 15196 8223

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(59.548) (59548) (595) 0 15198

(44945) (44945) (449) 0 15198

(30196) (30196) (302) 0 15198

13817

13955

14458

14603

14749

14896 15300

(86183) 6

(72229) 5

(59548) 4

(44945) 3

(30196) 2

0 1

454 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Calc Residual

Feb
15000

Mar
15000

Apr
15300

May
15300

Jun
15300

Jul
15300

The amount of the redemption is 8223, being calculated using the opening value of 72229, plus the further advance of 10000. The Adjusted Opening is the Opening Value adjusted for the further advance and the redemption.

The When to Pay? Option

0 = Pay at end of period (the default) 1 = Pay at start of Period Setting this option allows the user to regulate when payments are made to the account. An account where payments occur at the start of the period will incur lower charges overall than one where payments are made at the end because the interest charges will be lower. It might be helpful to format this item on a D-List consisting of a single item named Start with an IID of 1. An entry should only be made for this option in the first period of the loan, it cannot be varied during the life of the account. No entry must be made if you require payments at the end of each period. Both advances and redemptions are assumed to occur at the start of a period. The When to Pay flag only affects the original advance and the regular repayments.

Example 4 A Loan with payments at the start of each period

A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the start of each month. In month 3 a further advance of 10000 is made with a residual value of 2000. In month 4 an early redemption of 10% is made. This is example 3 with When to Pay set to 1:

Jan Feb
Advance Amount Residual value No of Periods When To Pay Rate (100000) 15000 6 1 Start 1.00%

Mar

Apr
(10000) 2000

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

User Guide 455

Chapter 12: Built in Functions (BiFs)

Jan Feb
Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (86183) 6 15000 13817 2 Yes 2 Yes 14670

Mar

Apr

May
10.00%

Jun

Jul

2 Yes 2 Yes

2 Yes 2 Yes 2050 (72229) (82229) (655) 0 16720

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (853) 0 14670 (715) 0 14670

(66164) (59548) (445) 0 15048 6616

(44945) (44945) (299) 0 15048

(30196) (30196) (151) 0 15048

13955

16065

14603

14749

14896 15300

(72229) 5 15000

(66164) 4 17000

(44945) 3 15300

(30196) 2 15300

0 1 15300

The monthly payments are less than those for example 3. The monthly interest is less each month than in example 3 because the payment is deducted from the opening balance before the interest for the month is calculated. Interest is still compounded (added to the account) at the end of each period.

The Compound? Option

This option allows the user to set interest compounds which are less frequent than the payments to the account. This will typically happen where monthly payments are made but interest is compounded quarterly, half-yearly, or annually. See Appendix 1 for how to convert an annual interest rate to rate per period in these circumstances. 1 = No

456 Analyst

Chapter 12: Built in Functions (BiFs) 2 = Yes (the default) It may be helpful to format this item on a D-List consisting of the two items NO and YES, whose IID numbers are 1 and 2 respectively. If no entry is made to this setting in any given period, the interest will be compounded in that period. To illustrate the difference made by not compounding interest, three examples are given below.

Example 5 A typical consumer credit type loan

This is the same as example 1. This type of loan typically runs on a monthly timescale and also has interest compounded monthly. A loan of 100000 over 6 months at a rate of 1% per month with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

2 Yes 2 Yes 14817

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(72229) (72229) (722) 0 14817

(58134) (58134) (581) 0 14817

(43899) (43899) (439) 0 14817

(29521) (29521) (295) 0 14817

User Guide 457

Chapter 12: Built in Functions (BiFs)

Jan
Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
13817

Mar
13955

Apr
14094

May
14235

Jun
14378

Jul
14521 15000

(86183) 6 15000

(72229) 5 15000

(58134) 4 15000

(43899) 3 15000

(29521) 2 15000

0 1 15000

Compound? defaults to 2 = Yes if no entry is made. Accrued interest is zero throughout because interest is compounded in every period. The interest rate must be completed for each period of the loan.

Example 6 A loan with monthly payments and quarterly interest compounds

A loan of 100000 over 6 months at a rate of 1% per month. Payments are made at the end of each month. Interest is compounded at the end of March and at the end of June. LeaseVariable automatically compounds the interest in July, the last period of the loan irrespective of the flag that has been set.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

1 No 2 Yes 14817

2 Yes 2 Yes

1 No 2 Yes

1 No 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (85183)

(72219)

(57405)

(42591)

(29502)

458 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr
(72219) (722) 0 14814

May
(57405) (574) (722) 14814

Jun
(42591) (426) (1296) 14810

Jul
(29502) (295) 0 14797

(100000) (85183) (1000) 0 14817 (852) (1000) 14817

13817

13965

14092

14240

14384

14502 15000

(85183) 6 15000

(72219) 5 15000

(57405) 4 15000

(42591) 3 15000

(29502) 2 15000

0 1 15000

The interest rate must be entered in every period. In periods where the interest is compounded, the interest is added to the closing balance: Closing Value = Opening Value + Interest this Period + Accrued Interest - Payment. In periods where interest is not compounded, the interest is shown as accrued interest for the following periods and is not added to the closing balance: Closing Value = Opening Value - Payment. In the last period @LeaseVariable automatically compounds the interest and recalculates the payment to ensure that the Closing Value comes to zero.

Example 7 A loan with monthly payments and compounds on set dates

It is important to note that @LeaseVariable does not look forward to the settings in future periods for the Rate and Compound? options. In each period the payment is calculated according to the values of the variables in that period, assuming that the loan will be repaid over the remaining periods at that rate with interest compounded in every period. The effect is, if interest is not compounded in future periods, the payment calculated will be slightly too high. If the Recalculate? option is set to default of Yes, the repayments will be revised downwards in each period where interest has not been compounded. If Recalculate? is set to No, repayments will continue at the higher level. Note: It is not possible to use LeaseVariable to calculate a constant payment for future periods that will bring the account to zero if interest is not compounded in every period. If the previous example is revised so that the compound is set in June only, the following payment values are obtained: User Guide 459

Chapter 12: Built in Functions (BiFs)

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

1 No 2 Yes 14817

1 No 2 Yes

1 No 2 Yes

1 No 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (85183) (100000) (85183) (1000) 0 14817 (852) (1000) 14817

(70367) (70367) (704) (1852) 14814

(55553) (55553) (556) (2556) 14808

(40745) (40745) (407) (3111) 14795

(29469) (29469) (295) 0 14763

13817

13965

14110

14252

14387

14469 15000

(85183) 6 15000

(70367) 5 15000

(55553) 4 15000

(40745) 3 15000

(29469) 2 15000

0 1 15000

A payment of 14817 is calculated in the first period whether or not interest is compounded in any of the subsequent periods (see examples 5 (p. 457), 6 (p. 458) and 7 (p. 459)).

460 Analyst

Chapter 12: Built in Functions (BiFs) After the second month of the loan, the payment value gradually decreases because the capital value of the loan is slightly lower in each period where interest is not compounded. Interest is automatically compounded in the last period. If Recalculate? had been set to 1 (No) in each period, the payments would continue at a steady rate of 14817 with the result that the account would be overpaid and the closing value would not be zero.

Recalculate?
This option allows the user to specify when payments to the loan should be recalculated to take into account changes in interest rate, which may occur during the life of the loan. This option can also be used where interest compound is less frequent than the payments to the account. You may decide you want to recalculate the payments every period, as in Example 3 (p. 452). @Lease Variable automatically adjusts the payment in each period to take into account further advances and early redemptions. Therefore if Recalculate? is set to No in any given period, the payment used for that period will be the payment from the previous period adjusted only for further advances and redemptions. 1 = No 2 = Yes (the default) Note: The Recalculate? option will only make a difference to the calculated payments if there are interest rate changes during the life of the loan and/or interest is not compounded in every period. It may be helpful to format this item on a D-List consisting of the two items NO and YES, whose IID numbers are 1 and 2 respectively. If no entry is made to this setting in any given period, the payment will be re-calculated in that period. @LeaseVariable gives the user the option whether or not to re-calculate the payment to take into account changes to interest rates in each period. If you choose not to re-calculate, payments will carry on at their existing rate until you do choose to re-calculate. The exception occurs if there is a further advance or redemption, which will always trigger a recalculation, regardless of whether the Recalculate flag is set to Yes or No. A similar situation is that of a repayment mortgage. When interest rates change, some lenders notify borrowers and adjust the monthly payments immediately. Others however only review the repayments on an annual basis, either their own year end or the anniversary of the loan. In the intervening months borrowers continue to pay at the same rate regardless of interest rate changes. If rates rise, they are paying slightly too little, if they fall, they are paying slightly too much. When the loan reaches its review date, the payments for the next twelve months are calculated based on the balance outstanding, the remaining term of the loan and the interest rate then prevailing. Note: To ensure the closing balance of the account always comes to zero, it is advisable to set Recalculate to 2 =Yes, or leave it blank in the last period of an account. The following examples illustrate the difference made by not recalculating payments.

User Guide 461

Chapter 12: Built in Functions (BiFs)

Example 8 Recalculating for Interest Rate changes

In this example it is assumed that interest is being compounded in every period. If the interest rate remained constant throughout the loan then the payment would also remain constant. A loan of 100000 over 6 months at a rate of 1% per month for 2 months, then 2% per month for 4 months with interest compounded monthly. The residual value will be 15000. Payments are made at the end of each month. The following is an example of immediate recalculation.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

2.00%

2.00%

2.00%

2.00%

2 Yes 2 Yes 14817

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(72229) (72229) (1445) 0 15330

(58344) (58344) (1167) 0 15330

(44181) (44181) (884) 0 15330

(29735) (29735) (595) 0 15330

13817

13955

13885

14163

14446

14735 15000

(86183)

(72229)

(58344)

(44181)

(29735)

462 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Periods Remaining Calc Residual

Feb
6 15000

Mar
5 15000

Apr
4 15000

May
3 15000

Jun
2 15000

Jul
1 15000

The payment in April is revised upwards to take into account the rate change and continues at the higher level. The following is an example of not changing payments for a rate change and reviewing repayments in June.

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

2.00%

2.00%

2.00%

2.00%

2 Yes 1 No 14817

2 Yes 1 No

2 Yes 1 No

2 Yes 1 No

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (86183) (100000) (86183) (1000) 0 14817 (862) 0 14817

(72229) (72229) (1445) 0 14817

(58857) (58857) (1117) 0 14817

(45217) (45217) (904) 0 15863

(30258) (30258) (605) 0 15863

13817

13955

13372

13639

14959

15258

User Guide 463

Chapter 12: Built in Functions (BiFs)

Jan
Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr

May

Jun

Jul
15000

(86183) 6 15000

(72229) 5 15000

(58857) 4 15000

(45217) 3 15000

(30258) 2 15000

0 1 15000

Payments continue at the original rate so the account is being underpaid. When payments are revised in June they have to rise by a larger amount to ensure that the account is repaid on time.

Example 9 The effect of Recalculate? where interest is not compounded in every period
As shown in Example 7 (p. 459), where interest is not compounded in every period, then the calculated payment is slightly too high to bring the account to zero at the close if there are no rate changes. Using Recalculate = Yes in every period will mean that the payment is adjusted in each period to keep the account on track. Alternatively you might prefer to budget constant payments for a whole year, for example, simply bringing the account back into line on an annual basis. If you wish to ensure that the account comes to zero in the last period, you should always allow the payment to be re-calculated in the last period. The following is an example of recalculating repayments in every period:

Jan
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value

Feb
(100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1.00%

1 No 2 Yes 14817

1 No 2 Yes

1 No 2 Yes

1 No 2 Yes

2 Yes 2 Yes

2 Yes 2 Yes

(100000) (85183)

(70367)

(55553)

(40745)

(29469)

464 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr
(70367) (704) (1852) 14814

May
(55553) (556) (2556) 14808

Jun
(40745) (407) (3111) 14795

Jul
(29469) (295) 0 14763

(100000) (85183) (1000) 0 14817 (852) (1000) 14817

13817

13965

14110

14252

14387

14469 15000

(85183) 6 15000

(70367) 5 15000

(55553) 4 15000

(40745) 3 15000

(29469) 2 15000

0 1 15000

Repayments decrease slightly in every period to take into account non-compounded interest. The next example is of recalculation of payments in June only:

Jan Feb
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate Compound ? Recalculate ? Calc Payment 1 No 1 No 14817 1.00% (100000) 15000 6

Mar

Apr

May

Jun

Jul

1.00%

1.00%

1.00%

1.00%

1.00%

1 No 1 No

1 No 1 No

1 No 1 No

2 Yes 2 Yes

2 Yes 2 Yes

User Guide 465

Chapter 12: Built in Functions (BiFs)

Jan Feb
Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (85183) 6 15000 13817

Mar

Apr
(70367) (70367) (704) (1852) 14817

May
(55550) (55550) (556) (2556) 14817

Jun
(40734) (40734) (407) (3111) 14789

Jul
(29463) (29463) (295) 0 14758

(100000) (85183) (100000) (85183) (1000) 0 14817 (852) (1000) 14817

13965

14113

14261

14382

14463 15000

(70367) 5 15000

(55550) 4 15000

(40734) 3 15000

(29463) 2 15000

0 1 15000

The account has been slightly overpaid each month as payments continued at their original level so the payment can drop to a lower level in June.

Using the input variables in combination

Repayments are recalculated in every period to take into account interest rate changes and non-compound of interest.

Jan Feb
Advance Amount Residual value No of Periods When To Pay Rate Redemption Rate 1.00% (100000) 15000 6

Mar

Apr
(10000) 2000

May

Jun

Jul

2.00%

2.00%

2.00% 10.00%

3.00%

3.00%

466 Analyst

Chapter 12: Built in Functions (BiFs)

Jan Feb
Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual (85183) 6 15000 13817 1 No 2 Yes 14817

Mar
1 No 2 Yes

Apr
1 No 2 Yes 2141 (69781) (79781) (1596) (2704) 17538

May
1 No 2 Yes

Jun
2 Yes 2 Yes

Jul
1 No 2 Yes

(100000) (85183) (100000) (85183) (1000) 0 14817 (1704) (1000) 15402

(62243) (56019) (1120) (4299) 15916 6224

(40103) (40103) (1203) (5420) 16254

(30472) (30472) (914) 0 16086

13698

15942

14796

15050

15172 15300

(69781) 5 15000

(62243) 4 17000

(40103) 3 15300

(30472) 2 15300

0 1 15300

The following example shows recalculation of payments at points in time:

Jan
Advance Amount Residual value No of Periods When To Pay Rate

Feb
(100000)

Mar

Apr
(10000)

May

Jun

Jul

15000

2000

1.00%

2.00%

2.00%

2.00%

3.00%

3.00%

User Guide 467

Chapter 12: Built in Functions (BiFs)

Jan
Redemption Rate Compound ? Recalculate ? Calc Payment Opening Value Adjusted Opening Interest This Period Accrued Interest Payment Redemptions Capital Paid Residual Paid Off Closing Value Periods Remaining Calc Residual

Feb

Mar

Apr

May
10.00%

Jun

Jul

1 No 1 No 14817

1 No 1 No

1 No 1 No 2141 (70367)

1 No 1 No

2 Yes 1 No

1 No 2 Yes

(100000) (85183)

(63409)

(41806)

(33251)

(100000) (85183)

(80367)

(57068)

(41806)

(33251)

(1000)

(1704)

(1607)

(1141)

(1254)

(998)

(1000)

(2704)

(4311)

(5452)

14817

14817

16958

15262 6341

15262

18949

13817

13113

15350

14120

14008

17951 15300

(85183) 6

(70367) 5

(63409) 4

(41806) 3

(33251) 2

0 1

15000

15000

17000

15300

15300

15300

The same account without recalculating repayments each month. Repayments are still changed to take into account the further advance in April and the redemption in May, but interest changes and non-compounding are not calculated in until June and July.

468 Analyst

Chapter 12: Built in Functions (BiFs)

Messages and input ranges Multiple Accounts

For any slice of a D-Cube, LeaseVariable will only calculate a value in the first period where Nper is greater then zero. Inputs to the Nper or When to Pay in any subsequent time period will be ignored. The warning message below will be displayed. @LeaseVariable only deals with one loan or annuity at a time. The calculation inputs are in period Period xx for {slice name}. You have non-zero inputs in other periods, the first such period is Period xx, at {cube name}, {slice name}. The warning message can be viewed by clicking the yellow square in the top left corner of the cube.

Insoluble inputs
If your inputs present a case that cannot be solved, this warning message appears in the calculation errors: @LeaseVariable in period {period-name} of slice {slice-name} cannot be solved with your inputs, where {slice-name} = item-name1; item-name2; & with one name for each dimension in the D-Cube, excluding the time and the LeaseVariable dimensions.

Time Scales
The @LeaseVariable BiF assumes that the time scale is composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

Error Message
If the timescale contains gaps between the periods or overlapping period, the following error message is displayed: @LeaseVariable invalid time scale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

Warning Message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 (lunar or calendar month). The length in days of all periods is between 89 and 92 (calendar quarters). The length in days of all periods is between 120 and 123 (3 periods per year). The length in days of all periods is 365 or 366 (years).

Otherwise you see the warning message:

User Guide 469

Chapter 12: Built in Functions (BiFs) @LeaseVariable time scale {time scale D-List name} has periods of unequal lengths. The calculations are performed exactly the same, whether the message is there or not.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Signs of Input Variables

A calculation warning is displayed where an account is defined with the Advance Amount and Residual Value having the same sign.

Appendix 1: Behavior of Interest

Interest is expressed as a rate per period. Similar to other BiFs in this family, the timescale must consist of equal consecutive periods. For information about timescales, see "Timescales" (p. 447). However variable interest rates are allowed with this BiF. It is not mandatory to compound interest in every period. You could, for example, have monthly payments to the account with interest charged quarterly. In periods where interest is compounded, it is compounded at the end of the period.

Examples of Interest Rates.

Suppose you have a timescale consisting of four equal quarters. If the annual rate is 12%, and the interest is compounded annually, the rate per period is 12/ 4, or 3%.

Quarterly Timescale - Annual Compounds Annual Interest 12%

Interest Rate per Period Compound this period? Opening Balance Interest for Period Accrued Interest Closing Balance 100

Quarter 1
3.00% No 100 3

Quarter 2
3.00% No 100 3 3 100

Quarter 3
3.00% No 100 3 6 100

Quarter 4
3.00% No 100 3 9 112

However, if interest is compounded quarterly, the rate per period is

470 Analyst

Chapter 12: Built in Functions (BiFs)

Quarterly Timescale - Quarterly Compounds Annual Interest 12%

Interest Rate per Period Compound this period? Opening Balance Interest for Period Accrued Interest Closing Balance 102.87

Quarter 1
2.87% Yes 100 2.87

Quarter 2
2.87% Yes 102.87 2.96 0.00 105.83

Quarter 3
2.87% Yes 105.83 3.04 0.00 108.87

Quarter 4
2.87% Yes 108.87 3.13 0.00 112.00

If monthly payments are made to the account but interest remains compounded quarterly so that the timescale consists of months, you could treat the three months as equal periods and use a rate per period in each of 2.87/3, or 0.96%.

Monthly Timescale - Annual Compounds Quarterly Interest 2.87% (=1. 12^0.25 -1)
Interest Rate per Period Compound this period? Opening Balance Interest for Period Accrued Interest Closing Balance 100.00 0.96% No 100 0.96 0.96% No 100 0.96 0.96 100.00 0.96% Yes 100 0.96 1.92 102.87

Month 1

Month 2

Month 3

Quarter Total
2.87% N/A 100 2.87 0.00 102.87

Alternatively, if the months were January (31 days), February (28 days), and March (31 days), you could use a rate per period of (2.87 *31/90) or 0.99% in January and March, and (2.87 *28/90) or 0.89% in February.

User Guide 471

Chapter 12: Built in Functions (BiFs)

Monthly Timescale - Quarterly Compounds Quarterly Interest 2.87% (=1. 12^0.25 -1)
Interest Rate per Period Compound this period? Opening Balance Interest for Period Accrued Interest Closing Balance 100.00 0.99% No 100.00 0.99 0.89% No 100.00 0.89 0.89 100.00 0.99% Yes 100.00 0.99 1.88 102.87

Month 1

Month 2

Month 3

Quarter Total
2.87% N/A 100.00 2.87 0.00 102.87

@Linavg
Averaged= @Linavg(Original) Input/Output Parameter
Original Averaged Result Input BiF Result D-List Item D-List Item

Description
The original series to be averaged (sales) The linear average (average sales)

How Linavg works

Linavg calculates a linear average that applies a larger weighting to more recent periods. It is called linear because the weights applied decrease linearly as you go back in time.

Example: Average sales = @Linavg(Sales) Jan

Sales Average Sales 1000 1000

Feb
2000 1667

Mar
1500 1583

Apr
2200 1830

May
1750 1803

Jun
2000 1860

The Feb Average is calculated by giving Feb a weighting of 2 and Jan a weight of 1: Feb Average =(1000*1 + 2000*2)/(1+2) =5000/3 472 Analyst

Chapter 12: Built in Functions (BiFs) =1,667

Formula used by Linavg

Steps to Use this BiF

1. Create a calculation D-List. Refer to the table above for item names. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Average Sales. 3. Click Change item attributes. 4. Click BiF. 5. Select Linavg from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@Mix
Mixed=@Mix(SwitchOver;Actual;Forecast) Input/Output Parameter
Actual Switchover Input Input Param D-List Item

Description
Actual historic data The last historic period is that which contains the switchover date

None 19970501 DList

Treat all periods as historic May1,1997 Use switchover date in timescale D-List

User Guide 473

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
Today 5 Forecast Mixed Input BiF Result D-List Item D-List Item

Description
Use today's date Use May Forecast or plan Mixes historic actual data with future forecast figures

How Mix works

The Mix BiF mixes historic actual data prior to the SwitchOver date with a forecast at and after the switchover date. For example Mixed=@Mix(4;Actual;Forecast) gives a switchover date of April. This uses Actual data up to and including March, Forecast data from April onwards.

Jan
Actual Forecast Mix 120 100 120

Feb
140 100 140

Mar Apr
130 100 130 0 100 100

May Jun
0 100 100 0 100 100

Jul
0 100 100

Aug Sep
0 100 100 0 100 100

Oct
0 100 100

Nov Dec
0 100 100 0 100 100

Formula for Mix

If the current period is before the period containing the switchover date: Mixed = Actual If the current period comes on or after the switchover date: Mixed = Forecast

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display the mixe" l of historic actuals with a future forecast. 4. Click Change item attributes. 5. Click BiF. 6. Select Mix from the Function Name list. 7. Enter the SwitchOver parameter. 474 Analyst

Chapter 12: Built in Functions (BiFs) For generic monthly timescale D-Lists only, type the period number (for example 4 for April). For timescale D-Lists defined by dates, type the switchover date (for example, 19980401 to use 1st April 1998 or Today to use todays date). Alternatively type Dlist to use the switchover date contained in the timescale D-List. 8. Select items for Actual and Forecast parameters by double-clicking on items in the right hand list. 9. Click Finish. 10. Click Apply. 11. Save the D-List.

@Movavg & @Movsum

MovAvg=@Movavg(Style;Method;Prime;Original)
Note: For MovSum, read sum instead of average in the parameter descriptions below.

Input/Output
Style Input param

Description
The style parameter is a letter which describes the style of the average followed by an integer (minimum value 2) which is the number of periods to include in the average or sum. If the first character is missing, then style L is assumed. L5 L is for Last. For example L5=Average of last 5 periods including current period. C is for Center. For example C3=Average of previous, current & next. The average is returned in the center of the n periods averaged. If the number of periods of a center average is even, it will return the average of two consecutive averages or sums. F is for First. For example F4=Average of the next 4 periods including current period.

C3

F4

User Guide 475

Chapter 12: Built in Functions (BiFs)

Input/Output
W1,2,1

Description
W is for Weightings that allows you to specify the weighting applied to each period. The weights are always central moving averages. They should always be symmetrical and separated by commas. The length of the moving average is the number of weights. Thus W1,2,1 applies a weighting of 2 to the current period, 1 to the previous and next periods. If adding up a sum, MovSum scales the weightings approximately. Thus W1,2,1 gives the sum of (1*previous+2*current+1*next)*3/4.

Method

Input param

The method is a letter which describes how to fill the periods at the start and end for which data is missing. R Replicate the first and/or last input periods as many times as needed. Prime input variable is used to provide the missing averages that cannot be calculated because the original data is not available. Take the average or sum of the data if it is available. When calculating a moving sum with method T, any truncated sums required are scaled up to carry their full weight. For example, if you are calculating a 5 period sum but only 3 periods are available, it will be scaled up by a factor of 5/3. Unequal length averages. Unequal=(Left+Right)/2 using the full length on the side where it is available, and the longest available on the other side. Linear extrapolation is used to provide the missing inputs.

W2,1/1,1 Weights provided in formula to calculate the missing inputs. The individual weightings should be separated by commas, and each set separated by slashes.

476 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output
Prime Input D-List Item

Description
The values to be used instead of the average or sum results for early or late periods where data is missing. Usually this is a D-List item, but it could be a constant. For example, if you want a zero displayed when data is missing from a moving average calculation you might enter the value 0 for Prime. The original series to be averaged or summed.

Original

Input

D-List Item D-List Item

MovAvg/ MovSum

BiF Result

The moving average or sum over n periods.

How Movavg and Movsum work

The Movavg and Movsum built in functions calculate a moving average or moving sum over specified periods. For example, MovAvg=@Movavg(L3;P;Prime;Original) returns a linear average over the last three periods. If the data does not go back far enough, the item, Prime, provides the missing averages.

Jan
Prime Data MovAvg 1000 1000 1000

Feb
0 2000 1333

Mar
0 3000 2000

Apr
0 2000 2333

May
0 2000 2333

Jun
0 8000 4000

Jul
0 6000 5333

Aug
0 8000 7333

Sep
0 7000 7000

Oct
0

Nov
0

Dec
0 9000 6667

10000 1000 8333 6000

As another example, MovAvg=@Movavg(C3;T;;Original) gives a three-period central moving average. It returns an average of the previous, current, and next periods. Suppose that, in Jan, the previous months data is not available; the calculation takes just Jan Original (Method T).

Jan
Prime Data MovAvg 1000 1000 1000

Feb
0 2000 2000

Mar
0 3000 2333

Apr
0 2000 2333

May
0 2000 4000

Jun
0 8000 5333

Jul
0 6000 7333

Aug
0 8000 7000

Sep
0 7000 8333

Oct
0

Nov
0

Dec
0 9000 9000

10000 1000 6000 6667

MovAvg= @Movavg(C4;T;;Original) gives a four-period central moving average. If the number of periods of a center average is even, it will return the average of two consecutive averages.

User Guide 477

Chapter 12: Built in Functions (BiFs)

Jan
Prime Data MovAvg 1000 1000 1000

Feb
0 2000 2000

Mar
0 3000 2125

Apr
0 2000 3000

May
0 2000 4125

Jun
0 8000 5250

Jul
0 6000 6625

Aug
0 8000 7500

Sep
0 7000 7125

Oct
0

Nov
0

Dec
0 9000 9000

10000 1000 6625 6667

For example, April is calculated by taking the average of the two 4 period averages, Feb-May and Mar-Jun. April = ((2000+3000+2000+2000)/4+(3000+2000+2000+8000)/4)/2 = 3000 In February, 4 months of data are not available, so Feb and Nov are calculated as a C3 average. Movavg= @Movavg(C5;U;;Original) gives a five-period central moving average. The Unequal length method (U) is used for the end conditions. For example, suppose Feb MovAvg is missing data from Dec of the previous year; it calculates based on an average going back 1.5 periods (the average of mid Feb to Jan) and an average going ahead of 2.5 periods (mid Feb to Mar). Feb Movavg = Average of (Jan+0.5*Feb)/1.5 and (0.5*Feb+Mar+Apr)/2.5.

Jan
Prime Data MovAvg 1000 1000 1600

Feb
0 2000 1867

Mar
0 3000 2000

Apr
0 2000 3400

May
0 2000 4200

Jun
0 8000 5200

Jul
0 6000 6200

Aug
0 8000 7800

Sep
0 7000 6400

Oct
0

Nov
0

Dec
0 9000 7600

10000 1000 7000 6667

In this example, Feb is therefore ((1000+2000*.5)/1.5+(2000*.5+3000+2000)/2.5)/2 = 3733/2 = 1867. MovAvg=@Movavg(W1,2,1;R;;Original) uses a style where a weighting of 2 is applied to the current period and a weighting of 1 is applied to the previous and next periods. This is similar to a central average but gives more weight to the current period. For example, suppose that Mar MovAvg = (110+(120*2)+160)/4 = 127.5. To calculate Jan and Dec moving averages, method (R) replicates the first and last periods to provide the missing data.

Jan
Prime Data MovAvg 1000 1000 1250

Feb
0 2000 2000

Mar
0 3000 2500

Apr
0 2000 2250

May
0 2000 3500

Jun
0 8000 6000

Jul
0 6000 7000

Aug
0 8000 7250

Sep
0 7000 8000

Oct
0

Nov
0

Dec
0 9000 7000

10000 1000 7000 5250

In this example, Feb is calculated as (1000+2000*2+3000)/4 = 4000/2 = 2000.

478 Analyst

Chapter 12: Built in Functions (BiFs) MovAvg=@Movavg(L3;W2,1/1,1;;Original) calculates an average of the last 3 periods. In Jan you will be missing 2 periods of data from the previous year so it uses the specified weightings (2*Jan) +(1*Feb) instead. In Feb you will be missing 1 period so it uses (1*Jan)+(1*Feb) instead. You can be quite specific as to how you want to calculate each average for early (or late) periods and can use as many periods of original data as you want. However, if you are using the weighting method, you must set a weighting pattern for every period where data is missing. The weightings are separated by slashes for each period where data is missing.

Jan
Prime Data MovAvg 1000 1000 1333

Feb
0 2000 1500

Mar
0 3000 2000

Apr
0 2000 2333

May
0 2000 2333

Jun
0 8000 4000

Jul
0 6000 5333

Aug
0 8000 7333

Sep
0 7000 7000

Oct
0

Nov
0

Dec
0 9000 6667

10000 1000 8333 6000

In this example, January is calculated as (1000*2+2000)/3 = 4000/3 = 1333. MovAvg= @Movavg(C5;W3,1/4,2,1;;Original) gives a five-period central moving average. The periods Jan, Feb, Nov, and Dec are missing some periods that are needed so the weighting method is used instead to calculate the averages for these periods.

Jan
Prime Data MovAvg 1000 1000 1250

Feb
0 2000 1571

Mar
0 3000 2000

Apr
0 2000 3400

May
0 2000 4200

Jun
0 8000 5200

Jul
0 6000 6200

Aug
0 8000 7800

Sep
0 7000 6400

Oct
0

Nov
0

Dec
0 9000 7000

10000 1000 7000 6857

In this example, Feb is therefore calculated as Feb = (4*1000+2*2000+1*3000)/7 = 11000/7 = 1571.

Formulas for Movavg and Movsum

The formula for a moving average is: MovAvg = Sum of Originals over n periods/ Number of periods to be averaged. The formula for a moving sum is: MovSum = Sum of Originals over n periods. The relationship between the moving sum S and the moving average A is that S=A*length, where length is the length of the moving average. The choice of which originals to include in the formula depends on the style of average and the method of dealing with end conditions for missing data.

User Guide 479

Chapter 12: Built in Functions (BiFs) Methods R for replicate and L for linear extrapolation estimate the values for the missing periods. Methods P for prime, T for take, U for unequal, and W for weightings estimate the result directly. R for Replicate: The first and last original periods are replicated as many times as needed. This is the simplest rule and is used as the default if you do not specify another method. L for Linear extrapolation: The missing n periods at the front of the original series are provided by extending the line joining the centers of the first and second set of n periods of the original series. The missing periods at the back are provided in the same way by extending the line joining the last two sets of n input periods to the right. P for Prime: Get the unavailable averages from another variable. This is typically used to use a constant (zero say) as strictly speaking the data is not available, but if you know the missing data you can enter it here in the Prime variable. T for Take: Takes an average over as many periods as there is data available but does not extrapolate or estimate any further. For example using a 3 period last average style (L3) with method T for the end conditions would give an average of (Jan/1) in Jan, (Jan+Feb)/2 in Feb and (Jan+Feb+Mar)/3 in Mar. Method T is not permitted with style W. U for Unequal: U calculates separate right and left averages using the largest average available and then averaging the two averages. This is a better variant of the "T for Take" method for the centered styles C. For styles F and L method U is the same as method T. The central period is shared between the two averages. Method U is not permitted with style W. W for user Weights: This option gives you the flexibility to provide appropriate weights for the data being averaged/summed. A set of weights is provided for each missing average or sum for styles L and F. For the centered styles C and W a set of weights is provided for half of the series, the same weights being used to fill the front and the back of the smoothed series.

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display the moving average or moving sum result. 4. Click Change item attributes. 5. Click BiF. 6. Select Movavg or Movsum from the Function Name list. 7. Enter the Style. For example, enter L3, for the average of the last 3 periods, C3 for the average of previous, current, and next periods, F5 for the average of the last 5 periods or W1,3,1 to use your own weightings. Fractions of integers are ignored. Omitting the length or using an average sum with length of less than 2 periods will result in an error. 8. Enter the Method.

480 Analyst

Chapter 12: Built in Functions (BiFs) For example, enter R to replicate first/last periods, P to use Prime input for missing averages, T to average based on a truncated series if all the data is not available, U for unequal length averages, L to provide missing data by linear extrapolation, or W2,1/1,1 to use weights provided in formula. If you use the weightings method, ensure you provide a set of weightings for each period where the average cannot be calculated due to missing data. 9. If you have chosen method P to fill in for missing averages, select the item that contains the item, Prime, by double-clicking the item from the Items list. 10. Select the item that contains the Original by double-clicking the item from the Items list. 11. Click Finish. 12. Click Apply. 13. Save the D-List.

MoveMed
MovMed=@Movmed(Value; Length; Offset; Exclude)
The @MoveMed built in function takes the median value after sorting all input values into ascending sequence. If the number of input values is even, it takes the average of the middle two numbers. You use the @MoveMed built in function similarly to @MoveAvg. An average is calculated by adding numbers together and then dividing the total by the amount of numbers. The median is calculated as the middle value in a set of statistical values that are arranged in ascending or descending order.

Function
Input Input

Movmed
Value Length

Finds median
Values: the variable whose median is required

Time Totals
Normal

Length: number of periods over which to take the Average median Offset: The number of periods offset from the center Exclude: 0 = include; 1 = exclude The median Average

Input

Offset

Input Result

Exclude Median

Average Normal

Length
This is the length of the moving median, it specifies how many periods are to be used to calculate the median. Typically it is an odd integer and the input values from periods on either side are used to calculate the median. Thus a five month moving median in June is calculated from the input values from April to August. User Guide 481

Chapter 12: Built in Functions (BiFs) The length can vary from period to period, this is most useful near the edge of the timescale. If you use lengths of 1 3 5 5, ..., 5 5 3 1 as your median lengths, then you get the first value in the first period, the median of the first three periods in the second period, and then lots of 5 period medians until the last two periods of the timescale. Length should be a positive integer. Movmed uses the absolute value rounded down to the next integer. When length is zero, the median will be zero.

Offset
This specifies which input periods are used to calculate each median. The default is zero, which means show the medians centrally. Where the length is even, there is no central period, so the centered median is the average of two adjacent medians. So a centered six month moving median for June is the average of the medians for March to August and for April to September. The offset is useful near the edge of the timescale, if you have: length = 3 3 5 5 5, ..., 5 5 5 3 3 and offset = 1 0 0 0 0, ..., 0 0 0 0 -1, then you get the same median of the first three periods in the first two periods, and the median of the last three periods in the last two periods. The offset means how far to the right you must look to find the center of the median. A negative value is used when you want to look to the left. This method based, on the central period, allows a default offset of zero to mean use central medians. Thus to show the median of Jan, Feb and Mar, in Jan use a length of 3 and an offset of 1. Offset should be an integer when length is odd, but halves may be used when the length is even. Thus a six period median for June with an offset of 0.5 is the median of April to September, while an offset of -0.5 uses March to August. Invalid offset values are rounded down to the next valid value towards zero. If offset is so small or large, that none of the periods needed to calculate the median are in the timescale, then the resulting median is zero.

Exclude
The exclude flag prevents a period contributing to any median. If you calculate a 5 period median, and one of its inputs is excluded by having {exclude} = 1, then you calculate the median of the other four periods. You do not want to exclude any valid data from a median unless your data has missing values. The only way you can handle this in a BiF is by using the exclude flag.

Missing Inputs
When the exclude flag removes values, or the length and offset settings point to periods outside the timescale, you may not have all the values needed to calculate the median using the length requested. If so, the median is calculated using whatever remaining values are available. If no values are left, the result will be zero.

Same Median Throughout Example

In a 13 period time scale, with length = 13 and offset = 6 5 4 3 2 1 0 -1 -2 -3 -4 -5 -6, you get the same 13 period median as the answer for all periods.

482 Analyst

Chapter 12: Built in Functions (BiFs)

Annual Median Example

In a 24 month timescale, to fill each 12 months with the years median, use: length = 12; and offset = 5.5 4.5 3.5 2.5 1.5 0.5 -0.5 -1.5 -2.5 -3.5 -4.5 -5.5 5.5 4.5 3.5 2.5 1.5 0.5 -0.5 -1.5 -2.5 -3.5 -4. 5 -5.5.

When Value Increases By One Each Period

The same value line is used as input by each example, it illustrates how using a central median keeps the median on a long term trend:

Period Jan
value length 1 5

Feb
2 5 2.5 5 0 2.5 5 2 4 5 2 1.5 5 1 3 6 2.75

Mar
3 5 3 5 0 3 5 2 5 5 2 2 5 0 3 6 3.25

Apr
4 5 4 5 0 4 5 2 6 5 2 2.5 5 0 4 6 4

May
5 5 5 5 0 4.5 5 2 7 5 2 3 5 0 5 6 5

Jun
6 5 6 5 0 5.5 5 2 8 5 2 4 5 0 6 6 6

Jul
7 5 7 5 1 7 5 2 9 5 2 5 5 0 7 6 7

Aug
8 5 8 5 0 8.5 5 2 10 5 2 6 5 0 8 6 8

Sep
9 5 9 5 0 9.5 5 2 11 5 2 7 5 0 9 6 9

Oct
10 5 10 5 0 10 5 2 11.5 5 2 8 5 0 10 6 10

Nov
11 5 11 5 0 11 5 2 12 5 2 9 5 0 11 6

Dec
12 5 11.5 5 0 11.5 5 2 12.5 5 2 10 5 1 11 6

Jan
13 5 12 5 0 12 5 2 13 5 2 11 5 2 11 6

median 2 length 5

exclude 0 median 2 length offset 5 2

median 3 length offset 5 2

median 1 length offset 5 2

median 3 length 6

median 2.25

10.75 11.25 11.75

User Guide 483

Chapter 12: Built in Functions (BiFs)

Period Jan
length offset 6 0.5

Feb
6 0.5 3

Mar
6 0.5 3.5

Apr
6 0.5 4.5

May
6 0.5 5.5

Jun
6 0.5 6.5

Jul
6 0.5 7.5

Aug
6 0.5 8.5

Sep
6 0.5 9.5

Oct
6 0.5 10.5

Nov
6 0.5 11

Dec
6 0.5 11.5

Jan
6 0.5 12

median 2.5

Note: Where offset is non-zero or the values required to calculate a median are missing, the result goes off the long term trend line

@Nper
Nper = @Nper(Rate; PMT; PV; FV; Type; CFV; Payments; Opening Value; Closing Value; Interest Paid; Periods left) Input/Output Parameter
Rate Input D-List Item

Description
Interpreted as a percentage but must be the rate per period. The value of the account at the start of the calculation. Can be zero. The value of the account at the end of the calculation. Would be zero for a loan which repays completely. The constant payment applied to the account each period. 0 means the payment to the account is made at the end of the period and is the default. 1 means the payment to the account is made at the start of the period. The number of periods for which the account must run to satisfy the input criteria. This will always be returned as the nearest integer.

PV

Input

D-List Item

FV

Input

D-List Item

PMT

Input

D-List Item

Type

Input 0 or 1 only

D-List Item

Nper

Result

D-List Item

484 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
CFV Output D-List Item

Description
The calculated future value of the account. The calculated end cashflow to or from the account based on your inputs of PV, PMT, Rate, and Type, and the calculated integer value for Nper. It is possible for this value to be different from your input value for FV. Will be equal to Closing Value with the opposite sign in the final period of the account.

Payments Output

D-List Item

Optional Item. Returns the value of PMT in every period for which the account operates. Optional item. If included, the BiF returns here the opening balance of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period. Optional item. If included, the BiF returns here the closing balance of the account. Should be set as a time average, last period. Optional Item. If Type = 0 will equal Opening Value * Rate per Period/100. If Type = 1 will equal (Opening Value + Payment) * Rate per Period/100.

Opening Value [start]

Output

D-List Item

Closing Value [end] Interest Paid

Output

D-List Item

Output

D-List Item

Periods left

Output

D-List Item

Optional Item. Will be Nper in the first calculation period and will reduce by 1 in each subsequent period.

How Nper works

Nper calculates the number of periods over which the account must run. The account must fulfill the following conditions: Either start value or finish value or both must be non-zero. The account runs for a set number of equal consecutive periods. A constant interest rate applies, compounded to the account at the end of each period (a zero rate is allowed). A payment of constant amount is applied to the account in each period. The user can apply the payment to the account either at the start or the end of the period.

User Guide 485

Chapter 12: Built in Functions (BiFs)

Example 1
Consider a regular savings account. The account opens with a balance of 10000 The interest rate is 0.5% per period An investor makes payments of 500 to the account at the end of each period When the account finishes,12000 is paid to the investor Nper will calculate the number of periods over which the account must run.

So, in this example PV = 10000 FV = -12000 Rate = 0.5 PMT = 500 Type = 0

Note: FV is input as a negative number because the account repays this amount to the investor whereas other payments are made from the investor to the account. It is possible to set this calculation against a single item D-List used as a timescale to produce the value for Nper. Account Present value 10000 Payment 500 Rate Per Period 0.50 % Type Future Value (12000) No Of Periods 4.00 Calculated Future Value (12216.56)

Account
Present Value Payment Rate Per Period Type 10000 500 0.50 %

486 Analyst

Chapter 12: Built in Functions (BiFs)

Account
Future Value No Of Periods Calculated Future Value (12000) 4.00 (12216.56)

Alternatively the calculation may be set against a longer timescale in which case the whole account will be scheduled - here the account is started at period 1. Note: The calculation starts in the first period for which Nper is non-zero. Inputs to PV, FV Rate PMT or Type in any other period will be ignored.

Period 1
Present value Payment Rate Per Period Type Future Value No Of Periods Calculated Future Value Opening Value Closing Value Interest Paid Payments Periods left (12000) 4.00 (12216.56) 10000 500 0.50 %

Period 2 Period 3 Period 4 Period 5 Period 6

10000.00 10550.00 50.00 500.00 4

10550.00 11102.75 11658.26 0.00 11102.75 11658.26 12216.56 0.00 52.75 500.00 3 55.51 500.00 2 58.29 500.00 1 0.00 0.00 0

0.00 0.00 0.00 0.00 0

Sometimes only part of the account falls within the timescale - in this case the account starts in period 5 and the closing balance value in the period 6 column indicates the balance of the account at the end of the timescale. This value, together with the Periods left figure could be used as a start values to schedule the rest of the account against another timescale following on from the one shown here.

User Guide 487

Chapter 12: Built in Functions (BiFs)

Period 1 Period 2 Period 3 Period 4 Period 5

Present value Payment Rate Per Period Type Future Value No Of Periods Calculated Future Value Opening Value Closing Value Interest Paid Payments Periods left (12000) 4.00 (12216.56) 10000 500 0.50 %

Period 6

10000.00 10550.00 50.00 500.00 4

10550.00 11102.75 52.75 500.00 3

Example 2 - A series of loan contracts

Suppose you have three separate loans as follows

Start Period
Contract A Contract B Contract C Period 1 Period 1 Period 4

Rate
0.5% 0.3% 0.6%

Start Value
10000 50000 5000

Payment
3360 13000 1025

Using the Nper BiF, it is possible to calculate the number of periods for each loan and make a schedule for each. It is also possible to split the payment of each period into the amount used to pay interest and the amount of capital reduction. To do this, add an extra item to your calculation D-List named Capital Paid and set the calculation field for this item to be Payments + Interest Paid 488 Analyst

Chapter 12: Built in Functions (BiFs) When creating the calculation D-Cube, this time there are three dimensions - Nper Calculation, Periods and Contracts. The Contracts D-List consists of the 3 contracts, A, B and C and a Total.

Step 1
Input the details of each contract on its own page, in the column for the relevant period. In each case FV will be zero because the loans are to be repaid completely. The start value of each loan is paid from the account to the borrower so PV is input as a negative figure. Periodic payments are then made from the borrower to the account to repay the loan so PMT is input as a positive figure.

Contract C
Present value Payment Rate Per Period Type Future Value No Of Periods Calculated Future Value Opening Value Closing Value Interest Paid Payments Capital Paid Periods left

Period 1

Period 2

Period 3

Period 4
(5000) 1025 0.6% 0 0.00 5.00 (35.06)

Period 5

Period 6

(5000.00) (4005.00) (30.00) 1025.00 995.00 5

(4005.00) (3004.03) (24.03) 1025.00 1000.97 4

(3004.03) (1997.05) (18.02) 1025.00 1006.98 3

Step 2
After the details of each contract have been completed, go to the TOTAL CONTRACTS page to view the totals for each period.

User Guide 489

Chapter 12: Built in Functions (BiFs)

Contract TOTAL
Present value Payment Rate Per Period Type Future Value No Of Periods Calculated Future Value Opening Value Closing Value

Period 1

Period 2

Period 3

Period 4

Period 5

Period 6

(60000)

(5000)

16360 0.8%

0 0.0%

0 0.0%

1025 0.6%

0 0.0%

0 0.0%

0 0

0 0

0 0

0 0

0 0

0 0

7.00

0.00

0.00

5.00

0.00

0.00

(1611.50)

0.00

0.00

(35.06)

0.00

0.00

(60000.00)

(43840.00)

(27624.90)

(16334.23)

(4005.00)

(3004.03)

(43840.00)

(27624.90)

(11354.50)

(2373.24)

(3004.03)

(1997.05)

Interest Paid (200.00) Payments 16360.00

(144.90) 16360.00 16215.10 5

(89.60) 16360.00 16270.40 3

(64.00) 14025.00 13961.00 6

(24.03) 1025.00 1000.97 4

(18.02) 1025.00 1006.98 3

Capital Paid 16160.00 Periods left 7

If the Timescale D-List you are using contains sub-total and Total fields, it will be necessary to set some items in the calculation D-Lists as Time Averages in order to obtain sensible figures in the Total Fields. PV and Opening Value should be set to First Period whilst Future Value, Number Of Periods, Calculated Future Value, Closing Value and Periods left should be set to Last Period. None of the Input items PV, PMT, FV, Nper, or Type give meaningful results against a Time Total because these are single column inputs specific to the period to which they relate, and it is not possible to aggregate them over time. However, the rows making up the account schedule (Payments,

490 Analyst

Chapter 12: Built in Functions (BiFs) Opening Value, Closing Value, Interest Paid and Capital Paid) are meaningful in Time Total fields so long as the correct averages have been set as shown above. Over the 6 periods, this company has paid 65155 in loan repayments. Of this, 540.56 was to cover interest and 64614.44 went to reduce the capital balances on the loans.

Formula used by Nper

Start[1+nper]=End[nper]= -FV When rate is zero, then Nper =-(PV+FV)/PMT When rate is not zero: Nper =

where rate = {%rate}/100 and Inter = (1+type*rate)*pmt/rate

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List. 2. Click the Calculation cell of the item to which you want to apply the Nper BiF. 3. Click Change item attributes. 4. Click BiF. 5. Select Nper from the Function Name list. 6. Click Next. 7. Enter the Rate parameter by selecting a D-List item or typing a constant. If typing a constant, remember that it is the rate per period which should be entered. An annual interest rate of 12% should therefore be entered as 12 if the periods in the timescale are years, but as 1 if the periods are months. 8. Enter the PMT parameter by selecting a D-List item. 9. Enter the PV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 10. Enter the FV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. The calculation starts in the first period for which Nper is non-zero. Inputs to PV, FV Rate Nper, or Type in any other period will be ignored. Ensure that either the PV or FV are completed, they cannot both be zero. 11. Enter the Type parameter by selecting a D-List item or entering either 0 or 1. A 0 denotes payments made at the end of each period, and 1 denotes payments made at the start of each period.

User Guide 491

Chapter 12: Built in Functions (BiFs) 12. Enter the Opening Value, Closing Value, Interest Paid, and Periods left parameters by selecting a D-List item for each. Completion of these fields is optional. 13. Click Finish. 14. Click Apply. 15. Save the D-List. Note: The Opening Value, Closing Value, Interest Paid, and Periods left calculation fields contain the word Output in the calculation field. Click this and you will see the calculation @From (Nper). This field is calculated by the Nper BiF, which cannot be edited or removed.

Messages and input ranges Number of periods

The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Insoluble inputs
If your inputs present a case that can not be solved, this warning message appears in the calculation errors @Nper in period {period-name} of slice {slice-name} can not be solved with your inputs where {slice-name} = item-name1; item-name2; with one name for each dimension in the cube, excluding the time and the PMT dimensions. When you see this message, both Nper and Rate are set to zero in that slice only. All other slices are calculated normally. The present value is the start and end value for all periods of the loan, with zero payments and zero interest.

Where PMT exactly equals Interest Paid

If the payments to the account in each period exactly equal the interest, but are of the opposite sign, the balance of the account does not move and the account could run for any number of periods. In this case Nper returns a value of 2 and the following message is displayed: @NPer returns number of periods = 2 in period xxxx for slice xxxx. The payments equal the interest, so the value is constant and you get the same answer for any number of periods.

Time Scales
The Nper BiF assumes that the time scale is composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

492 Analyst

Chapter 12: Built in Functions (BiFs)

Error message
If the time scale contains gaps between the periods or overlapping period, you will see the following error message: @Nper invalid time scale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

Warning message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 lunar or calendar months. The length in days of all periods is between 89 and 92 calendar quarters. The length in days of all periods is between 120 and 123 (3 periods each year). The length in days of all periods is 365 or 366.

If none of the tests are true, this warning message is displayed: @Nper time scale {time scale D-List name} has periods of unequal lengths The calculations are performed exactly the same, whether the message is there or not.

@NPV
NPV = @NPV(Rate; Values; Date Flag; Payment Date) Definition
Net Present Value is the sum of a series of cashflow values each discounted to the period where NPV is calculated based on the rate input by the user in that period.

Using the NPV BiF Input/Output

Rate Input

Parameter
D-List Item

Description
The annual rate at which future values are to be discounted. The series of cash values for which the NPV is to be calculated. Date of Payment: 1 = Start; 2 = Middle; 3 = End; 4 = User. Used to define when, during the period, the payment takes place, and can be set up as a D-List formatted item.

Values

Input

D-List Item

Date Flag

Input

D-List Item

User Guide 493

Chapter 12: Built in Functions (BiFs)

Input/Output
Payment Date Input

Parameter
D-List Item

Description
When date flag = 4, this date will be used. This field should be date formatted unless a generic monthly timescale is in use in which case a numeric input to this field is permitted. The numbers 1 to 30 may be used where 1 means the first and 30 means the last day of the month. The Net Present Value of the series of cashflows.

NPV

Output

D-List Item

How NPV Works

NPV calculates the sum of a series of future cashflow values after discounting each to a present value based on the annual rate input for the period in which it is being calculated. The calculation for NPV always looks forward so any values or dates in previous periods are ignored in the calculation. There is no restriction on the number of future payments and the periods between the payments do not need to be equal.

Examples Evaluating a project

Suppose a company is considering whether to purchase a machine which will have a useful life of 5 years and is expected to generate the following extra profits: Year 2001 = 1000 Year 2002 = 2500 Year 2003 and following 4000 The machine would be purchased on 12th October 2000 and would cost 10000. Alternatively the 10000 could be invested for 5 years at a rate of 4% per annum. If the NPV at 12th October 2000 of the future profits exceeds 10000, the purchase price of the machine, then this would be a worthwhile investment. A positive NPV for 2000 would therefore signify a worthwhile investment.

2000
Rate Values 4.00% (10000)

2001
0.00% 1000 3- End

2002
0.00% 2500 3- End

2003
0.00% 4000 3- End

2004
0.00% 4000 3- End

2005
0.00% 4000 3- End

2006
0.00% 0

Date Flag 4 - User Date 12/10/00

494 Analyst

Chapter 12: Built in Functions (BiFs)

2000
NPV 3419.27

2001

2002

2003

2004

2005
4000.00

2006
0.00

15500.00 14500.00 12000.00 8000.00

The rate set in the Rate row for the period in which NPV is being calculated will be used to discount all future cashflows in the sequence. The percentage rate per annum should be input.

A Mathematical justification
Consider an investment which requires a payment from you of 100000 on 31st December 2001 and repays 110000 on 31st December 2002. A periodic time scale with payments one year apart is used here to simplify the calculations.

2000
Rate Values 5.00% 0

2001
5.00% (100000) 3- End

2002
5.00% 110000 3- End

2003
0.00% 0 3- End

2004
0.00% 0 3- End

2005
0.00% 0 3- End

2006
0.00% 0

Date Flag 3 - End Date NPV 4535.15

4761.90

110000.00

0.00

0.00

0.00

0.00

To find the NPV at 31st December 2000 of the first value, consider what sum (X) you would have to invest at 5% to achieve a balance of -100000 after 365 days. So, X 1 + 5%( X1 ) = -100000 X1 = (-100000) / (105/100) X1 = -95238 Now, to find the NPV of 110000 on 31st December 2002, at 31st December 2000, consider what sum, (X 2), you would have to invest at 5% per annum to achieve this final balance. So, X2 + 5%( X2 ) + 5%( X2 + 5%( X2 )) = 110000 (105/100) X2 + 5%((105/100) X2 ) = 110000 (105/100) * (105/100) X2 = 110000 X2 = 110000 / (105/100)^2 X2 = 99773 And NPV 2000 = X1 + X2 = -95238 + 99773 = 4535. Similarly,

User Guide 495

Chapter 12: Built in Functions (BiFs) NPV, 2001 = [-100000] + [110000/(1.05)] = -100000 +104762 = 4762 NPV, 2002 = 110000

Using a Non-Periodic Timescale

Consider the following calculation:

Q1 2000
Rate Values Date Flag Date NPV 52474.18 5.00% (100000) 3 - End

Q2 2000
5.00% 60000 3- End

Q3 2000
5.00% 0 3- End

Q4 2000
5.00% 40000 3- End

2001
5.00% 50000 3- End

2002
5.00% 10000 3- End

154340.22

95507.56

96689.34

59523.81

10000

When calculating the net present value over periods of uneven length, the length of the period in days is taken into account. In quarter 4, there are 31+30+31= 92 days or 92/365= 0.252 of a year. To calculate the NPV for Q3 00, only payments in the future, for example: Q4 00, 2001 and 2002, are taken into account. The discount rate of 5% per annum is taken from quarter 3 and applied to all future cash streams. Using the argument, what must be invested at 5% per annum at the end of Q3 00 to give each of the future values we derive: NPV, Q3 00 = 0 + [40000/(1.05)^0.252] + [50000/(1.05)^1.252] + [10000/1.05)^2.252] = 39511 + 47037 + 8959 = 95508 In the above example, the value of 40000 has to be discounted over a 92 day period using the 5% annual rate. To do this, it is divided by
92 105 (100 ) ^ 365

If we were discounting over 1 year, the discounted balance would be 38095, (40000 /(105/100)). The year is now divided into two periods of 273 days and 92 days and we need to find the balance at the start of the 92 day period. Applying an interest rate of 5% per annum for 1 year multiplies the start balance by 1.05. If this rate is applied for another year, the original start balance will be multiplied by (1.05)2. In a year consisting of 2 periods of 273 and 92 days, the start balance is multiplied by an overall 1.05 made up of

496 Analyst

Chapter 12: Built in Functions (BiFs)

273 365 92 365

((1.05)

) * ((1.05)

which is equal to

((1.05)

365 365

to arrive at the end balance of 40000. So, to find the balance at the start of the 92 day period, we divide the end balance of 40000 by

((1.05)
Formula used by NPV

92 365

NPV(j) =

Where Pi is the Payment Value in the i th period: di is the i th or last Payment date. dj is the date at which the Net Present Value is being calculated so that di - dj means the number of days forward from the day where NPV is being calculated. Rate is the discount rate per annum to apply to values in future periods.

Steps to Use this BiF

1. Set up a D-Cube with a Timescale D-List and a Calculation D-List containing the items Rate, Values, Date Flag, Date and NPV. You may wish to format the Rate item with a percentage suffix and to the number of decimal places required. Entries for rate will be treated as annual percentages. Unless you are using a generic monthly timescale you should format the Date item to a suitable date format. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item to which you want to apply the NPV BiF. 4. Click Change item attributes. 5. Click BiF. 6. Select NPV from the Function Name list. 7. Click Next. 8. Enter the Rate parameter by selecting the Rate D-List item. 9. Enter the Values parameter by selecting the Values D-List item.

User Guide 497

Chapter 12: Built in Functions (BiFs) 10. Enter the Date Flag parameter by selecting the Date Flag D-List item, or enter a constant which may be 1 - start of period, 2 - middle of period, 3 - end of period, or 4 - User defined date. 11. Enter the Payment Date parameter by selecting the Date D-List item. 12. Click Finish. 13. Click Apply. 14. Save and close the D-List.

Messages and input ranges User Defined Dates

If the date flag is set to 4, then the user must define a date for that period in the Date row. The Date item in the calculation D-List is usually date formatted unless a monthly generic timescale is being used. If the payment date input falls outside the current period, then the closest valid date will be used and one of the following messages will be displayed: Payment date is before the first day of periods {period-names} of slice {slice-name} Payment date is after the last day for periods {period-names} of slice {slice-name} Where {slice-name} is item-name1; item-name2; &...;, one name for each dimension other than time and the one holding the BiF formula. If a monthly generic timescale is used, and Date Flag is set to 4, a number between 1 and 30 should be input for date where 1 means the first, and 30 means the last day of the month.

Invalid Rate Input

If the value of the rate input would cause the result to be too small, too large or imaginary, this message will appear in the calculation errors: @NPV rate is invalid in period {period-name}of slice {slice-name} A rate of -100%, for example, will cause this message to appear.

@Outlook
Outlook = @Outlook(Plan;Actual;Switchover) Input/Output
Plan Actual Switchover Input Input Input

Parameter
D-List Item D-List Item D-List Item

Description
The original plan Actual historic data The last historic period is that which contains the switchover date

498 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output

Parameter
None 1997051 DList Today 5

Description
Treat all periods as historic May1, 1997 Use switchover date in timescale D-List Use today's date Use May The outlook result combines historic actuals with a future plan

Outlook

BiF Result

D-List Item

How Outlook works

The outlook is calculated by merging actuals from past months with plan figures for future months while adjusting the forecast to stick to the original plan total. The period containing the switchover date is taken as the first future period. The outlook result for future periods is calculated by revising the plan. The revision is based on keeping the target figure for each time subtotal the same as the plan, taking into account the actual costs to date. In periods on and prior to the switchover date, the outlook result is calculated as equal to the historic actuals. The timescale must therefore contain at least one total. In the example shown, Outlook = @Outlook(Plan;Actual;8) uses a switchover period of 8 (August) . The Outlook for August and later months is based on a revised plan that tries to keep the Full Year Outlook the same as the Full Year Plan. The choice of which time subtotal Outlook sets as a target depends on how the formulas are set up. If the Full Year total is the sum of the months, the Outlook tries as far as possible to stick to the Full Year Plan. Full Year = Apr+May+Jun+Jul+Aug+Sep+Oct+Nov+Dec+Jan+Feb+Mar

Jan
Plan Actual

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

Total

1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000 12000 500 500 500 500 500 500 500 500 500 500 500 500 500 3500 1700 1700 1700 1700 1700 12000

Outlook 500

If the months are summed into quarters, and the quarters summed into years, as far as possible the revision will attempt to keep the quarterly subtotals the same as the Plan by adjusting future periods in the Outlook. The full year total will therefore differ by the same amount as the variance between plan and actual for Q2.

User Guide 499

Chapter 12: Built in Functions (BiFs)

Jan
Plan Actual Outlook 1000 500 500 Jul Plan Actual Outlook 1000 500 500

Feb
1000 500 500 Aug 1000

Mar
1000 500 500 Sep 1000

Q1
3000 1500 1500 Q3 3000 500

Apr
1000 500 500 Oct 1000

May
1000 500 500 Nov 1000

Jun
1000 500 500 Dec 1000

Q2
3000 1500 1500 Q4 12000 0

H1
6000 3000 3000 Total 12000 3500 9000

1250

1250

3000

1000

1000

1000

3000

Jul
Plan Actual Outlook 1000 500 500

Aug
1000

Sep
1000

Q3
3000 500

Oct
1000

Nov
1000

Dec
1000

Q4
3000 0

Total
12000 3500 9000

1250

1250

3000

1000

1000

1000

3000

Formula used by Outlook

If the current period is before the period containing the switchover date: Outlook = Actual If the current period comes on or after the switchover date, as far as possible the outlook is adjusted to meet the plan: Outlook, Full Year = Plan, Full Year Outlook, period n = Pro-rata allocation of ((Plan, Full Year) - (Sum of actuals to date)) Note: It is not necessarily the full year plan total on the time dimension that the outlook tries to meet. It could be the quarterly or half-yearly plan, depending on how the formulas in the time dimension are set up. The outlook will try to meet the plan totals that sum the periods directly rather than those that sum subtotals.

Steps to Use this BiF

1. Create a calculation D-List. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this example, Outlook. 3. Click Change item attributes. 500 Analyst

Chapter 12: Built in Functions (BiFs) 4. Click BiF. 5. Select Outlook from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish. 9. Click Apply. 10. Save the D-List.

@PMT
PMT = @PMT(Rate; Nper; PV; FV; Type; Opening Value, Closing Value; Interest Paid; Periods left) Input/Output
PV Input

Parameter
D-List Item

Description
The payment to or from the account at the start of the calculation. Can be zero. The payment to or from the account at the end of the calculation. Would be zero for a loan which repays completely. Interpreted as a percentage but must be the rate per period. The number of periods the account is to run 0 means the payment to the account is made at the end of the period and is the default. 1 means the payment to the account is made at the start of the period. The payment to the account which will be a constant amount each period. Provided the timescale is sufficiently long the BiF returns this amount in every period where a payment is due. Optional item. If included, the BiF returns here the opening value of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period.

FV

Input

D-List Item

Rate

Input

D-List Item

Nper Type

Input

D-List Item

Input 0 or 1 only D-List Item

PMT

Result

D-List Item

Opening Value [start]

Output

D-List Item

User Guide 501

Chapter 12: Built in Functions (BiFs)

Input/Output
Closing Value [end] Output

Parameter
D-List Item

Description
Optional item. If included, the BiF returns here the closing account balance. Will be equal to FV in the last account period. Should be set as a time average, last period.

Interest Paid

Output

D-List Item

Optional item. If Type = 0 will equal Opening Value * Rate per Period/100 If Type = 1 will equal (Opening Value + Payment) * Rate per Period/100

Periods left

Output

D-List Item

Optional Item. Will be Nper in the first calculation period and will reduce by 1 in each subsequent period.

How PMT works

PMT calculates the regular payment to an account for each period. The account must fulfill the following conditions: Either start value or finish value or both must be non-zero. The account runs for a set number of equal consecutive periods. A constant interest rate applies, compounded to the account at the end of each period. A zero rate is allowed. The user can choose to apply the payment to the account either at the start or the end of the period.

Example 1 - A savings account

Consider a regular savings account. The account opens with a balance of 10000.00 The interest rate is 0.5% per period After 4 periods the account repays 12000 to the investor Payments are made at the end of each period PMT will calculate the amount which the investor must pay into the account each period.

So, in this example PV = 10000 FV = -12000

502 Analyst

Chapter 12: Built in Functions (BiFs) Rate = 0.5 Nper = 4 Type = 0

Note: FV is input as a negative number because the account repays this amount to the investor whereas other payments are made from the investor to the account. It is possible to set this calculation against a single item d-list used as a timescale to produce the value for PMT.

Account
Present Value Future Value No of Periods Rate per period Type Payment 10000 (12000) 4 0.50% 0 446.27

Alternatively the calculation may be set against a longer timescale in which case the whole account will be scheduled - here the account is started at period 2: Note: The calculation starts in the first period for which Nper is non-zero. Inputs to PV, FV Rate Nper, or Type in any other period will be ignored.

Jan
Present value Future value No of periods Rate Type PMT 0.00

Feb
10000

Mar

Apr

May

Jun

(12000) 4

0.5%

446.27

446.27

446.27 446.27 0.00

User Guide 503

Chapter 12: Built in Functions (BiFs)

Jan
Opening Value Closing Value 0.00

Feb

Mar

Apr

May

Jun

10000.00 10496. 27 10496.27 10995. 01 50.00 4 52.48 3

10995. 11496. 0.00 01 25 11496. 12000. 0.00 25 00 54.98 2 57.48 1 0.00 0

0.00

Interest Paid 0.00 Periods left 0

Sometimes only part of the account falls within the timescale - in this case the account starts in period 5, and the closing balance value in the period 6 column indicates the balance of the account at the end of the timescale. This value, together with the Periods left figure could be used as a start values to schedule the rest of the account against another timescale following on from the one shown here.

Jan
Present value Future value No of periods Rate Type PMT Opening Value Closing Value Interest Paid Periods left 0.00 0.00 0.00 0.00 0

Feb

Mar

Apr

May
10000 (12000) 4 0.5%

Jun

0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0

446.27

446.27

10000.00 10496.27 10496.27 10995.01 50.00 4 52.48 3

Example 2 - A series of loan contracts

Suppose you have three separate loans as follows

504 Analyst

Chapter 12: Built in Functions (BiFs)

Start Period Number of Periods

Contract A Contract B Contract C Period 1 Period 1 Period 5 3 4 5

Rate per Period Start Value

0.5% 0.3% 0.6%

10000 50000 5000

Using the PMT BiF, it is possible to make a schedule for each contract and also to calculate the total you have to pay each month on the three loans. It is also possible to split the payment each period into the amount used to pay interest and the amount of capital reduction. To do this, add an extra item to your calculation D-List named Capital Paid and set the calculation field for this item to be: PMT + Interest Paid When creating the Calculation D-Cube, this time there are three dimensions - PMT Calculation, Periods, and Contracts. The Contracts D-List consists of the 3 contracts, A, B and C, and a Total.

Step 1
Input the details of each contract on its own page, in the column for the relevant period. In each case FV will be zero because the loans are to be repaid completely. PV is input as a negative number and the result PMT is returned as a positive number because the loan value is originally paid to you from the account. Periodic payments are then made from you to the account to repay the loan.

Contract A
Present value Future value No of periods Rate Type PMT Opening Value Closing Value Interest Paid

Jan
(10000)

Feb

Mar

Apr

May

Jun

3 0.5%

3366.72 (10000.00) (6683.28) (50.00)

3366.72 (6683.28) (3349.97) (33.42)

3366.72 (3349.97) 0.00 (16.75)

0.00 0.00 0.00 0.00

0.00 0.00 0.00 0.00

0.00 0.00 0.00 0.00 User Guide 505

Chapter 12: Built in Functions (BiFs)

Contract A
Capital paid Periods left

Jan
3316.72 3

Feb
3333.31 2

Mar
3349.97 1

Apr
0.00 0

May
0.00 0

Jun
0.00 0

Step 2
After the details of each contract have been completed, go to the Total Contracts page to view the totals for each period.

Contract TOTAL
Present value Future value No of periods Rate Type PMT Opening Value Closing Value

Jan

Feb

Mar

Apr

May

Jun

(60000)

(5000)

0.33%

0.60%

15960.61 (60000.00)

15960.61 (44239.39)

15960.61 (28424.86)

12593.81 (12556.22)

1018.07 (5000.00)

1018.07 (4011.93)

(44239.39)

(28424.86)

(12556.22)

0.00

(4011.93)

(3017.93)

Interest Paid (200.00) Capital paid 15760.61 Periods left 7

(146.08) 15814.53 5

(91.97) 15868.64 3

(37.67) 12556.22 1

(30.00) 988.07 5

(24.07) 994.00 4

If the Timescale D-List you are using contains Sub-total and Total fields it will be necessary to set some items in the Calculation D-Lists as Time Averages in order to obtain sensible figures in the Total Fields. Rate is set as a weighted average, weighted by PV.

506 Analyst

Chapter 12: Built in Functions (BiFs) Present value and Opening value should be set to First Period whilst Future Value, Closing Balance and Periods left should be set to Last Period. None of the Input items PV, FV, Nper, Rate or Type give meaningful results against a Time Total because these are single column inputs, specific to the period to which they relate and it is not possible to aggregate them over time. However, the rows making up the account schedule (PMT, Opening Value, Closing Value, Interest Paid and Capital Paid) are meaningful in Time Total fields so long as the correct averages have been set as shown above. Over the 6 periods, this company has paid 62511.87 in loan repayments. Of this, 529.80 was to cover interest and 61982.07 went to reduce the capital balances on the loans.

Formulas used by PMT

Start[1+nper]=End[nper]= -FV When rate is zero, then PMT=-(PV+FV)/Nper When rate is not zero: PMT=-(FV+PV*(1+rate)^nper) * rate/(1+type*rate)*(1+rate)*((1+rate)^nper-1) =-(FV+PV*NR) / Q
PMT = = -(FV+PV * (1+Rate) Nper ) * Rate (1 + Type*Rate) * ((1 + Rate) Nper - 1) -(FV + (PV*NR)) Q

where NR=(1+rate)Nper and Q=(1+type*rate)*(NR-1)/rate

Steps to Use this BiF

1. Set up a D-Cube with a Timescale D-List and a Calculation D-List. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item where you wish to calculate the PMT result. 4. Click Change item attributes. 5. Click BiF. 6. Select PMT from the Function Name list. 7. Click Next. 8. Enter the Rate parameter by selecting a D-List item or typing a constant. If typing a constant, remember that it is the rate per period which should be entered. 9. Enter the Nper parameter by selecting a D-List item. 10. Enter the PV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero.

User Guide 507

Chapter 12: Built in Functions (BiFs) 11. Enter the FV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. The calculation starts in the first period for which Nper is non-zero. Inputs to PV, FV Rate Nper, or Type in any other period will be ignored. Ensure that either the PV or FV are completed, they cannot both be zero. 12. Enter the Type parameter by selecting a D-List item or entering either 0 or 1. A 0 denotes payments made at the end of each period, and a 1 denotes payments made at the start of each period. 13. Enter the Opening Value, Closing Value, Interest Applied, and Periods left parameters by selecting a D-List item for each. Completion of these fields is optional. 14. Click Finish. 15. Click Apply. 16. Save the D-List. Note: The Opening Value, Closing Value, Interest Applied, and Periods left calculation fields contain the word Output in the calculation field. Click this and you will see the calculation @From (PMT). This field is calculated by the PMT BiF, which cannot be edited or removed.

Messages and input ranges Multiple Accounts

For any slice of a cube, PMT will only calculate a value in the first period where Nper is greater then zero. Inputs to fields in any subsequent time period will be ignored. The warning message below will be displayed: @PMT only deals with one loan or annuity at a time. The calculation inputs are in period Period xx for {slice name}. You have non-zero inputs in other periods - the first such period is Period xx, at {cube name}, {slice name}. Where you wish to calculate a number of accounts, include a sequence dimension in your cube and input the details for each account on a separate page.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Insoluble inputs
If your inputs present a case that can not be solved, this warning message appears in the calculation errors @PMT in period {period-name} of slice {slice-name} can not be solved with your inputs where {slice-name} = item-name1; item-name2; with one name for each dimension in the cube, excluding the time and the PMT dimensions.

508 Analyst

Chapter 12: Built in Functions (BiFs) When you see this message, both PMT and Rate are set to zero in that slice only. All other slices are calculated normally. The present value is the start and end value for all periods of the loan, with zero payments and zero interest.

Time Scales
The PMT BiF assumes that the time scale is a composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

Error message
If the time scale contains gaps between the periods or overlapping period, you will see the error message: @PMT invalid time scale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

Warning message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 lunar or calendar months. The length in days of all periods is between 89 and 92 calendar quarters. The length in days of all periods is between 120 and 123 (3 periods each year). The length in days of all periods is 365 or 366.

If none of the tests are true, the warning message is displayed: @PMT time scale {time scale D-List name} has periods of unequal lengths The calculations are performed exactly the same, whether the message is there or not.

@PV
PV = @PV(Nper; Rate; PMT; FV; Type; Opening Value, Closing Value; Interest Paid; Periods left) Input/Output
Nper Rates Input Input

Parameter
D-List Item D-List Item

Description
The number of periods the account is to run. Interpreted as a percentage but must be the rate per period. The constant payment applied to the account each period.

PMT

Input

D-List Item

User Guide 509

Chapter 12: Built in Functions (BiFs)

Input/Output
FV Input

Parameter
D-List Item

Description
The payment to or from the account at the end of the calculation. Would be zero for a loan which repays completely. 0 means the payment to the account is made at the end of the period and is the default. 1 means the payment to the account is made at the start of the period. The start value or opening payment to or from the account in the first period. Optional Item. Returns the value of PMT for every period in which the account operates. Optional item. If included, the BiF returns here the opening value of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period. Optional item. If included, the BiF returns here the closing balance of the account. Will be equal but with the opposite sign to FV in the last period of the account. Should be set as a time average, last period. Optional Item. If Type = 0 will equal Opening Value * Rate per Period/100 If Type = 1 will equal (Opening Value + Payment) * Rate per Period/100

Type

Input 0 or 1 only D-List Item

PV

Result

D-List Item

Payments

Output

D-List Item

Opening Value [start]

Output

D-List Item

Closing Output Value [end]

D-List Item

Interest Applied

Output

D-List Item

Periods left Output

D-List Item

Optional Item. Will be Nper in the first calculation period and will reduce by 1 in each subsequent period.

How PV works
PV calculates the required opening value for an account given the target closing balance and the conditions under which the account will run. The account must fulfill the following conditions: The account runs for a set number of equal consecutive periods. A constant interest rate applies, compounded to the account at the end of each period (a zero rate is allowed).

510 Analyst

Chapter 12: Built in Functions (BiFs) A payment of constant amount is applied to the account in each period. The user can apply the payment to the account either at the start or the end of the period.

Example 1 - A savings account

Consider a regular savings account. The interest rate is 0.5% per period An investor pays in 500 per period After 4 periods the account repays 12000 to the investor Payments are made at the end of each period

PV will calculate the amount which the investor must pay into the account at the start of period 1 to achieve a balance of 12000 after 4 periods have elapsed. So, in this example FV = -12000 PMT = 500 Rate = 0.5 Nper = 4 Type = 0

FV is input as a negative number because the account repays this amount to the investor whereas other payments are made from the investor to the account. It is possible to set this calculation against a single item D-List used as a timescale to produce the value for PV.

Account
Future Value PMT Rate per period No of periods Type PV (12000.00) 500.00 0.5% 4 0 9787.72

Alternatively the calculation may be set against a longer timescale in which case the whole account will be scheduled - here the account is considered to start at period 2: Note: The calculation starts in the first period for which Nper is non-zero. Inputs to PMT, FV Rate Nper or Type in any other period will be ignored. User Guide 511

Chapter 12: Built in Functions (BiFs)

Jan
Future Value PMT Rate per Period Number of Periods Type Present Value Opening Value Closing Value Interest Applied Payments Periods left 0.00 0.00 0.00 0.00 0.00 0

Feb
(12000.00) 500.00 0.5% 4 0 9787.72 9787.72 10336.66 48.94 500.00 4

Mar

Apr

May

Jun

0.00 10336.66 10888.34 51.68 500.00 3

0.00 10888.34 11442.79 54.44 500.00 2

0.00 11442.79 12000.00 57.21 500.00 1

0.00 0.00 0.00 0.00 0.00 0

Sometimes only part of the account falls within the timescale - in this case the account starts in period 5, and the closing balance value in the period 6 column indicates the balance of the account at the end of the timescale.

Jan
Future Value PMT Rate per Period Number of Periods Type Present Value Opening Value Closing Value 0.00 0.00 0.00

Feb

Mar

Apr

May
(12000.00) 500.00 0.5% 4 0

Jun

0.00 0.00 0.00

0.00 0.00 0.00

0.00 0.00 0.00

9787.72 9787.72 10336.66

0.00 10336.66 10888.34

512 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Interest Applied Payments Periods left 0.00 0.00 0

Feb
0.00 0.00 0

Mar
0.00 0.00 0

Apr
0.00 0.00 0

May
48.94 500.00 4

Jun
51.68 500.00 3

Example 2 - A series of loan contracts

Suppose you have three separate loans as follows

Start Period

Number of Periods
3 4 5

Rate per Period Payment

Contract A Contract B Contract C

Period 1 Period 1 Period 5

0.5% 0.3% 0.6%

3360 12500 1000

Using the PV BiF, it is possible to calculate the start value of each loan and make a schedule for each. It is also possible to split the payment each period into the amount used to pay interest and the amount of capital reduction. To do this, add an extra item to your Calculation D-List named Capital Paid and set the Calculation Field for this item to be Payments + Interest Paid When creating the Calculation D-Cube, this time there are three dimensions - PV Calculation, Periods, and Contracts. The Contracts D-List consists of the 3 contracts, A, B and C, and a Total.

Step 1
Input the details of each contract on its own page, in the column for the relevant period. In each case FV will be zero because the loans are to be repaid completely. Periodic payments are then made from you to the account to repay the loan so PMT is input as a positive figure.

Contract A
Future Value PMT Rate per Period

Jan
0.00 3360.00 0.5%

Feb

Mar

Apr

May

Jun

Number of Periods 3

User Guide 513

Chapter 12: Built in Functions (BiFs)

Contract A
Type Present Value Opening Value Closing Value Interest Applied Capital Paid Payments Periods left

Jan
0 (9980.03) (9980.03) (6669.93) (49.90) 3310.10 3360.00 3

Feb

Mar

Apr

May

Jun

0.00 (6669.93) (3343.28) (33.35) 3326.65 3360.00 2

0.00 (3343.28) 0.00 (16.72) 3343.28 3360.00 1

0.00 0.00 0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0.00 0.00 0

Step 2
After the details of each contract have been completed, go to the Total Contracts page to view the totals for each period.

Contract TOTAL
Future Value PMT

Jan

Feb

Mar

Apr

May

Jun

0.00 15860.00

0.00 1000.00 0.6% 5

Rate per Period 0.8% Number of Periods Type Present Value 7

0 (59607.27) 0.00 (43946.05) (28231.23) (145.18) 15714.82 0.00 (28231.23) (12462.61) (91.38) 15768.62 0.00 (12462.61) 0.00 (37.39) 12462.61

0 (4911.25) 0.00 (4911.25) (3940.71) (3940.71) (2964.36) (29.47) 970.53 (23.64) 976.36

Opening Value (59607.27) Closing Value (43946.05)

Interest Applied (198.78) Capital Paid 514 Analyst 15661.22

Chapter 12: Built in Functions (BiFs)

Contract TOTAL
Payments Periods left

Jan

Feb

Mar

Apr

May

Jun

15860.00 7

15860.00 5

15860.00 3

12500.00 1

1000.00 5

1000.00 4

If the Timescale D-List you are using contains sub-total and Total fields, it will be necessary to set some items in the Calculation D-Lists as Time Averages in order to obtain sensible figures in the Total Fields. Present Value and Opening Value should be set to First Period, while Future Value, Number of Periods, Closing Value, and Periods left should be set to Last Period. None of the Input items PMT, FV, Nper, Rate or Type give meaningful results against a Time Total because these are single column inputs specific to the period to which they relate and it is not possible to aggregate them over time. However, the rows making up the account schedule - Payments, Opening Value, Closing Value, Interest Paid and Capital Paid, are meaningful in Time Total fields so long as the correct averages have been set as shown above. Over the 6 periods, this company has paid 62080 in loan repayments. Of this, 525.84 was to cover interest and 61554.16 went to reduce the capital balances on the loans.

Formula used by PV
Start[1+nper]=End[nper]=-FV If Rate = 0 Then PV = (PMT * Nper) + FV If the rate is non-zero Then

PV =

-(PMT(1+(Rate*Type)) * (1 + Rate) Rate Nper (1 + Rate)

Nper

- 1) + FV)

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item where you wish to calculate the PV result. 4. Click Change item attributes. 5. Click BiF. 6. Select PV from the Function Name list.

User Guide 515

Chapter 12: Built in Functions (BiFs) 7. Click Next. 8. Enter the Nper parameter by selecting a D-List item. 9. Enter the Rate parameter by selecting a D-List item or typing a constant. If typing a constant, remember that it is the rate per period which should be entered. 10. Enter the PMT parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 11. Enter the FV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 12. Enter the Type parameter by selecting a D-List item or entering either 0 or 1. A 0 denotes payments made at the end of each period, and a 1 denotes payments made at the start of each period. 13. Enter the Opening Value, Closing Value, Interest Applied, and Periods left parameters by selecting a D-List item for each. Completion of these fields is optional. 14. Click Finish. 15. Click Apply. 16. Save the D-List. Note: The Opening Value, Closing Value, Interest Applied, and Periods left calculation fields contain the word Output in the calculation field. Click this and you will see the calculation @From (PV). This field is calculated by the PV BiF, which cannot be edited or removed.

Messages and input ranges Multiple Accounts

For any slice of a cube, PV will only calculate a value in the first period where Nper is greater then zero. Inputs to fields in any subsequent time period will be ignored. The warning message below will be displayed: @PV only deals with one loan or annuity at a time. The calculation inputs are in period Period xx for {slice name}. You have non-zero inputs in other periods, the first such period is Period xx, at {cube name}, {slice name}. Where you wish to calculate a number of accounts, include a sequence dimension in your cube and input the details for each account on a separate page.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

516 Analyst

Chapter 12: Built in Functions (BiFs)

Time Scales
The PV BiF assumes that the time scale is composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

Error message
If the time scale contains gaps between the periods or overlapping period, you will see the error message @PV invalid time scale {time scale D-List name} has overlaps and/or gaps when a dangerous time scale is used with @PMT or other BiFs. When this happens, all outputs and results of the BiF are set to zero for all slices.

Warning message
If any one of the following tests is true, no message is issued: All the periods have exactly the same length. The length in days of all periods is between 28 and 31 lunar or calendar months. The length in days of all periods is between 89 and 92 calendar quarters. The length in days of all periods is between 120 and 123 (3 periods each year). The length in days of all periods is 365 or 366.

If none of the tests are true, the warning message is displayed @PV timescale {timescale D-List name} has periods of unequal lengths The calculations are performed exactly the same, whether the message is there or not.

@Proportion
Proportion=@Proportion(StartDate;StopDate;Week type)
@Proportion allows you to enter a start and stop date and express the length in days as a proportion of the period length.

How Proportion works

Proportion all days = (Stop date - Start date) / (Period finish date - Period start date) Proportion working days is the same, but excludes weekends. For example, consider a timescale for the first half of year 2000 and set a start date of 1 April and an End Date of 25 June with the Proportion to be calculated on the number of working days (5 day week).

User Guide 517

Chapter 12: Built in Functions (BiFs)

2000
Start End Proportion

Jan
01/04/00 25/06/00 0

Feb
01/04/00 25/06/00 0

Mar
01/04/00 25/06/00 0

Apr
01/04/00 25/06/00 1

May
01/04/00 25/06/00 1

Jun
01/04/00 25/06/00 0.77

For Jan to Mar, the start date has not been reached so the Proportion is set to 0. For Apr to May the end date has not been reached so the Proportion is set to 1. In June 2000 there were 22 working days, and to the 25 June there were 17 working days so the proportion is calculated as 17/22 = 0. 77

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display Proportion. 4. Click Change item attributes. 5. Click BiF. 6. Click Proportion in the Function Name list. 7. Click Next. 8. Double-click the parameters in the BiF Function Wizard. Note: In the Week type box, specify a five-day, six-day, or seven-day week (0 = seven-day work week, 1 = five-day work week, and 2 = six-day work week). 9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@Rate
Rate = @Rate(Nper; PMT; PV; FV; Type; Guess; Payments; Opening Value; Closing Value; Interest Paid; Periods left) Input/Output
Nper Input

Parameter
D-List Item

Description
The number of periods the account is to run.

518 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output
PMT Input

Parameter
D-List Item

Description
The constant payment applied to the account each period. The value of the payment to or from the account at the start of the calculation. The value of the payment to or from the account at the end of the calculation. 0 means the payment to the account is made at the end of the period and is the default. 1 means the payment to the account is made at the start of the period. A guess on the rate. Defaults to zero if not completed. Use when there is more than one possible solution. The percentage rate per period for the account. Optional Item. Returns the value of PMT for every period in which the account operates. Optional item. If included, the BiF returns the opening value of the account. Will be equal to PV in the first calculation period. Should be set as a time average, first period. Optional item. If included, the BiF returns the closing balance of the account. Will be equal to FV with the opposite sign in the last period of the account. Should be set as a time average, last period. Optional Item. If Type = 0 will equal Opening Value * Rate per Period/100. If Type = 1 will equal (Opening Value + Payment) * Rate per Period/100

PV

Input

D-List Item

FV

Input

D-List Item

Type

Input 0 or 1 only D-List Item

Guess

Input

D-List Item

Rate

Result

D-List Item D-List Item

Payments Output

Opening Value [start]

Output

D-List Item

Closing Value [end]

Output

D-List Item

Interest Paid

Output

D-List Item

Periods left

Output

D-List Item

Optional Item. Will be Nper in the first calculation period and will reduce by 1 in each subsequent period. User Guide 519

Chapter 12: Built in Functions (BiFs)

How Rate works

Rate calculates the percentage interest rate per period for an account, given its start balance, end balance, payment amount per period and the number of periods over which the account operates. The solution is found by an iterative method so it is possible that, for a given set of inputs, there may be more than one solution or no solution. The account runs for a set number of equal consecutive periods. A constant interest rate applies, compounded to the account at the end of each period (a zero rate is allowed). A payment of constant amount is applied to the account in each period. The user can apply the payment to the account either at the start or the end of the period.

Example - A savings account

Consider a regular savings account. An investor opens the account with a deposit of 10000 The account runs for four periods An investor pays in 450 per period Payments are made at the end of each period After 4 periods the account repays 12000 to the investor

Rate will calculate the constant percentage rate which must be applied to the account in each period. So, in this example PV = -10000 PMT = 450 FV = -12000 Nper = 4 Type = 0 Guess = 0 (default value)

It is possible to set this calculation against a single item D-List used as a timescale to produce the value for Rate.

Account
Present Value Payment Future Value 10000.00 450.00 (12000.00)

520 Analyst

Chapter 12: Built in Functions (BiFs)

Account
Number Of Periods Type Guess Rate Per Period 4 0 0 0.5%

Alternatively the calculation may be set against a longer timescale in which case the whole account will be scheduled - here the account is considered to start at period 2: Note: The calculation starts in the first period for which Nper is non-zero. Inputs to PV, PMT, Rate Nper or Type in any other period will be ignored.

Jan
Present Value Payment Future Value Number of Periods Type Guess Rate Per Period Opening Value Closing Value Interest Paid Payments Periods left 0.00 0.00 0.00 0.00 0

Feb
10000.00 450.00 (12000.00) 4 0 0 0.5% 10000.00 10496.52 46.52 450.00 4

Mar

Apr

May

Jun

10496.52 10995.36 48.83 450.00 3

10995.36 11496.51 51.16 450.00 2

11496.51 12000.00 53.49 450.00 1

0.00 0.00 0.00 0.00 0

Sometimes only part of the account falls within the timescale - in this case the account starts in period 5 and the closing value in the period 6 column indicates the balance of the account at the end of the timescale.

User Guide 521

Chapter 12: Built in Functions (BiFs)

Jan
Present Value Payment Future Value Number of Periods Type Guess Rate Per Period Opening Value Closing Value Interest Paid Payments Periods left 0.00 0.00 0.00 0.00 0

Feb

Mar

Apr

May
10000.00 450.00 (12000.00) 4 0 0 0.5%

Jun

0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0

0.00 0.00 0.00 0.00 0

10000.00 10496.52 46.52 450.00 4

10496.52 10995.36 48.83 450.00 3

Example 2 - A series of loan contracts

Suppose you have three separate loans as follows

Start Period

Number of Periods
3 4 5

Start Value

Payment

Contract A Contract B Contract C

Period 1 Period 1 Period 5

10000 50000 5000

3360 13000 1025

Using the Rate BiF, it is possible to calculate the rate per period of each loan and make a schedule for each. It is also possible to split the payment each period into the amount used to pay interest and the amount of capital reduction. To do this, add an extra item to your calculation D-List named Capital Paid and set the calculation field for this item to be Payments + Interest Paid

522 Analyst

Chapter 12: Built in Functions (BiFs) When creating the calculation D-Cube, this time there are three dimensions - Rate Calculation, Periods, and Contracts. The Contracts D-List consists of the 3 contracts, A, B and C, and a Total.

Step 1
Input the details of each contract on its own page, in the column for the relevant period. In each case FV will be zero because the loans are to be repaid completely. The start value of each loan is paid from the account to the borrower so PV is input as a negative figure. Periodic payments are then made from the borrower to the account to repay the loan so PMT is input as a positive figure.

Contract A
Present Value Payment Future Value Number of Periods Type Guess Rate Per Period Opening Value Closing Value Interest Paid Capital Paid Payments Periods left

Jan
(10000.00) 3360.00

Feb

Mar

Apr

May

Jun

0.4% (10000.00) (6679.95) (39.95) 3320.05 3360.00 3

0.0% (6679.35) (3346.63) (26.68) 3333.32 3360.00 2

0.0% (3346.63) 0.00 (13.37) 3346.63 3360.00 1

0.0% 0.00 0.00 0.00 0.00 0.00 0

0.0% 0.00 0.00 0.00 0.00 0.00 0

0.0% 0.00 0.00 0.00 0.00 0.00 0

Step 2
After the details of each contract have been completed, go to the Total Contracts page to view the totals for each period.

User Guide 523

Chapter 12: Built in Functions (BiFs)

Contract TOTAL
Present Value Payment Future Value Number of Periods Type Guess Rate Per Period Opening Value Closing Value

Jan

Feb

Mar

Apr

May

Jun

(60000.00)

(5000.00)

16360.00

1025.00

2.0%

0.0%

0.0%

0.0%

0.8%

0.0%

(60000.00)

(44473.70)

(28740.36)

(12796.85)

(5000.00)

(4016.44)

(44473.70)

(28470.36)

(12796.85)

0.00

(4016.44)

(3024.73)

Interest Paid (833.70) Capital Paid 15526.30 Payments Periods left 16360.00 7

(626.66) 15733.34 16360.00 5

(416.49) 15943.51 16360.00 3

(203.15) 12796.85 13000.00 1

(41.44) 983.56 1025.00 5

(33.29) 991.71 1025.00 4

If the Timescale D-List you are using contains sub-total and Total fields, then it will be necessary to set some items in the calculation D-Lists as Time Averages in order to obtain sensible figures in the Total Fields. Present Value and Opening value should be set to First Period, while Future Value, Number Of Periods, Closing Value and Periods left should be set to last Period. None of the Input items PV,PMT, FV, Nper, or Type give meaningful results against a Time Total because these are single column inputs, specific to the period to which they relate and it is not possible to aggregate them over time. However, the rows making up the account schedule (Payments, Opening Value, Closing Value, Interest Paid and Capital Paid) are meaningful in Time Total fields so long as the correct averages have been set as shown above.

524 Analyst

Chapter 12: Built in Functions (BiFs) Over the 6 periods, this company has paid 64130 in loan repayments. Of this, 2154.73 was to cover interest and 61975.27 went to reduce the capital balances on the loans.

Formula used by Rate

Start[1+nper]=End[nper]= -FV Rate is the solution to the family equation for the BiFs PMT, PV, FV, Nper and Rate:

0 = ( PV * ((1 + Rate)

Nper

((1 + Rate) ) - 1 ) + pmt(1 + (Rate*type)) * + FV Rate

Nper

Rate is found by using an iterative method starting from the Guess figure. This defaults to zero, which is a good starting point for finding a solution. Starting from this value, successive estimates are calculated until the calculated value of FV is within .0000001 of the input value. If after 20 iterations this accuracy is not achieved, calculation stops, the rate is set to zero, and this message appears: @Rate did not converge from guess xxx after 21 iterations, unresolved error is xxxxx, rate is set to zero for slice xxxxx. Because an iterative method is used, there may be more than one solution or no solutions at all. If PV, FV and PMT are all input with the same sign then there will be no solution. If there is more than one solution, setting a non-zero value for guess may cause an alternative rate value to be returned.

Example using Guess

An investor pays 50 into a savings account at the end of each month for a 20 year period. After 20 years the account pays him 100000. At the start of the account an initial payment of 1000 is made to the investor.

Case 1
Present Value Payment Future Value Number Of Periods Type Guess Rate Per Period So, in this example: (1000.00) 50.00 (100000.00) 240 0 0 1.6%

User Guide 525

Chapter 12: Built in Functions (BiFs) PV = -1000 PMT = 50 Rate = -100000 Nper = 240 Type = 0

In the first case (case 1), Guess has been left at its default value of zero and the solution for rate is returned as 1.6% per period. In this case the periods are months; However, for case 1, the error warning message reads: @Rate in period Period 1 for case 1. Your solution is near 1.6%, you can find another solution between 4.0% and 5.0% with these inputs, at Fin BiFs - Rate.Rate Full List[Rate per Period] In case 2, the guess has been input at 4 and a solution of 5% per period is returned as the rate.

Case 2
Present Value Payment Future Value Number Of Periods Type Guess Rate Per Period (1000.00) 50.00 (100000.00) 240 0 4 5.0%

Note: In this case, this would mean an interest rate of 5% per month on the account balance. Again, there is an error warning message to alert you that there is an alternate solution for rate. Either rate works mathematically because the same rate is paid throughout the account, whether the balance is in debit or credit. Note: The values for rate are being shown to 1 decimal place. The actual values are 1.6494% and 4.9958% respectively. In both cases the account starts with a balance of 1000 overdrawn. If the lower rate is used, the interest applied in the first month is 16.49, which is easily covered by the payment of 50. The overdrawn balance will be paid off relatively quickly and the account will start to accumulate savings to which interest will be added at the same rate. If the higher rate is used, it will take much longer to pay off the initial 1000 balance as the first few payments will only just cover the interest each month. However, after the account moves into credit, interest is paid on the savings at the higher rate and thus the balance will grow more quickly.

526 Analyst

Chapter 12: Built in Functions (BiFs)

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List. 2. Open the Calculation D-List. 3. Click the Calculation cell of the item where you want to calculate the Rate result. 4. Click Change item attributes. 5. Click BiF. 6. Click Rate in the Function Name list. 7. Click Next. 8. Enter the Nper parameter by selecting a D-List item. 9. Enter the PMT parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 10. Enter the PV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. 11. Enter the FV parameter by selecting a D-List item or leaving this field blank, in which case it will be treated as zero. Note, either PV or FV must be non-zero. 12. Enter the Type parameter by selecting a D-List item or entering either 0 or 1. 0 denotes payments made at the end of each period, and a 1 denotes payments made at the start of each period. 13. Enter the Guess parameter by selecting a D-List item. 14. Enter the Opening Value, Closing Value, Payments, Interest Applied, and Periods left parameters by selecting a D-List item for each. Completion of these fields is optional. 15. Click Finish. 16. Click Apply. 17. Save the D-List. Note: The Opening Value, Closing Value, Payments, Interest Applied, and Periods left calculation fields contain the word Output in the calculation field. Click this and you will see the calculation @From (Rate). This field is calculated by the Rate BiF, which cannot be edited or removed.

Messages and input ranges Multiple Accounts

For any slice of a cube, Rate will only calculate a value in the first period where Nper is greater then zero. Inputs to fields in any subsequent time period will be ignored. The following warning message will be displayed:

User Guide 527

Chapter 12: Built in Functions (BiFs) @Rate only deals with one loan or annuity at a time. The calculation inputs are in period Period xx for {slice name}. You have non-zero inputs in other periods, the first such period is Period xx, at {cube name}, {slice name}. Where you wish to calculate a number of accounts, include a sequence dimension in your cube and input the details for each account on a separate page.

Number of periods
The number of periods must be a positive integer. The sign and fractional part of your input is ignored, so 4, -4.4 and 4.6 all mean 4 periods. There is no warning message when a negative number or a non-integer is in your input.

Insoluble inputs
If your inputs present a case that can not be solved, this warning message appears in the calculation errors: @Rate did not converge from guess xxx after 21 iterations, unresolved error is xxxxx, rate is set to zero for {slice-name}. where {slice-name} = item-name1; item-name2; with one name for each dimension in the cube, excluding the time and the Rate dimensions. When you see this message Rate is set to zero in that slice only. All the other slices are calculated normally. The effect is that the present value is the start and end value for all periods of the loan, with zero payments and zero interest.

Inputs with multiple solutions

When there is more than one possible solution, the following warning message appears: @Rate in period {slice name}. Your solution is near 1.6%, you can find another solution between x% and (x+1)% with these inputs. Entering a guess at the value of x will then return an alternative value for rate.

Time Scales
The Rate BiF assumes that the time scale is composed of contiguous periods with the same length. If the timescale used does not meet these criteria, one of the two following messages will appear in the calculation messages.

Error message
If the time scale contains gaps between the periods or overlapping period, you will see the error message: @Rate invalid time scale {time scale D-List name} with overlaps and/or gaps. When this happens all outputs and results of the BiF are set to zero for all slices.

Warning message
If any one of the following tests is true, no message is issued: 528 Analyst

Chapter 12: Built in Functions (BiFs) All the periods have exactly the same length. The length in days of all periods is between 28 and 31 lunar or calendar months. The length in days of all periods is between 89 and 92 calendar quarters. The length in days of all periods is between 120 and 123 (3 periods each year). The length in days of all periods is 365 or 366.

If none of the tests are true, the following warning message is displayed: @Rate timescale {timescale D-List name} has periods of unequal lengths The calculations are performed exactly the same, whether the message is there or not.

@Repeat
Use the @Repeat built in function in a timescale D-List to repeat data from a single period or group of periods through the time scale of the D-List. Use it to take control of the forecast after @SeasonLite analyzes the history. The @Repeat BiF has two inputs: Number: The number of periods of data to be repeated and is set by entering as a prime into the first time period of the timescale. Input: The series of values to be repeated.

Repeat can be used to copy seasonal factors through the timescale. Repeat can also be used in other contexts, for example to repeat the weekday flag 1 1 1 1 1 0 0 through a daily time scale, or to repeat a 5 4 4 pattern of the number of weeks through a monthly timescale.

@SeasonLite
{Forecast} = @SeasonLite(Method; ActFlag; Original; Factor)

Name
Method ActFlag Original Factor Forecast

Input/Output Description
Input Input Input Output Result There are 7 methods, see "Methods" (p. 530). 1 = actual, actual periods are used to calculate the seasonal factors The data to be seasonally adjusted The seasonal adjustment factors for your data = Original if ActFlag = 1, otherwise calculated as T * SF / 100

User Guide 529

Chapter 12: Built in Functions (BiFs) The @SeasonLite built in function performs seasonal adjustments of time to determine seasonal patterns in data. It is easier to use than @SeasonPro because it uses fewer methods, inputs, and outputs. If your data requires a set of options not available in @SeasonLite, or if you want additional outputs, then use @SeasonPro instead. SeasonLite is suitable for data with sufficient history - at least one whole year, although five or more years are preferred, and the data is of a multiplicative type, and any trend is straight line. Other methods should be used if you have a longer history and the seasonal factors have changed during the course of this history. SeasonLite and SeasonPro use the same programs to calculate their results, they differ only in the number of methods and input and output variables available.

How it Works
SeasonLite uses the available history periods to estimate the seasonal factors and a trend, and then applies the estimates to calculate a forecast for the other periods. The timescale must use periods of the same length, with the same number of whole periods per year throughout. The full SeasonPro model is O = T * C * S * W * I, where O is the Original data, T is the trend, C is the cyclical effect, S is the Seasonal effect, W is the working day effect, and I the irregular component. In SeasonLite the Cyclical and Working Day effects are not calculated, so the model is O = T * S * I. SeasonLite shows the seasonal factors as a percentages (S = SF / 100) and replicates them throughout the time scale. The forecast is set equal to the historical value in the actual periods and calculated as T * SF / 100 for forecast periods.

Methods
SeasonLite has seven methods which use selected combinations of the six independent SeasonPro methods. With SeasonLite methods 1, 6, and 7, the methods used depend on the number of available actual periods with original data. Method 1 is the default method.

##

Description

SeasonPro Method

Note

Based on the number of actuals: less than two complete years 141113 2 or more, but less than 4 years 4 or more, but less than 6 years 6 or more years 124111 121111 111111 141113 124111

2 3

Multiplicative, typical year, constant trend Multiplicative, whole year initial trend, final trend through adjusted

1, 2 1, 3

Multiplicative, average, centered MA, trend through adjusted 121111

1, 4

530 Analyst

Chapter 12: Built in Functions (BiFs)

##

Description

SeasonPro Method

Note

5 6 7

Multiplicative, medial, centered MA, trend through adjusted 111111 As method 1, but force constant trend As method 1, but force linear trend 1xx113 1xx111

1, 5 1, 6 1, 7

Notes
1. To choose the best SeasonLite method you must understand something of the SeasonPro methods, which are described below. 2. You might use this instead of method 1, even though you have more than 2 years of history. 3. You might use this instead of method 1, even though you have more than 4 years of history. 4. You might use this instead of method 1, even if you have 6 or more years of actuals. 5. You might use this instead of method 1, even if you have less then 6 years of actuals. 6. Use this method if you believe your data is most likely to stay constant, even though you have enough actuals to get a good estimate of the slope. 7. Use this method to use a linear trend, even though you have less than two years history.

Pro Method 1 - Basic method

1 = Multiplicative; 2 = Additive. All SeasonLite methods are Multiplicative. The multiplicative model is O = T * C * S * I, the arithmetic is O = T + C + S + I. In the multiplicative model the seasonal effects add up to the number of periods in a year, whereas in an arithmetic model they add up to zero. You might expect the minimum temperature in a month to be better represented by an arithmetic model, particularly if you want to compare the seasonal patterns of different places. You must use SeasonPro if you want to do this.

Pro Method 2 - Average method

1 = Medial average; 2 = MA average; 3 = Average year; 4 = Typical year. For each actual period, SF = 100 * {original} / {Trend estimate} gives a value for the seasonal factor. The {Trend estimate} is usually a moving average, which means with 6 years of history you only have 5 years of SF values. We look at each period over all its years to get one estimate for its factor. The preferred approach is to throw away the highest and lowest values and average the rest, this is the medial average. With 2 to 5 years of data (which means 2 to 4 SF values) SeasonLite averages all the available factors, this is the MA average.

User Guide 531

Chapter 12: Built in Functions (BiFs) With fewer than 2 years actual data we have to use the typical year method. For each period the {period average} is the average of its original values over all history years. The typical year is then a year of all the {period average} values and the seasonal factor for each period is {Factor} = 100 * {Period average} / {year total of period averages}.

Pro Method 3 - MA method

1 = centered MA; 2 = uncentered MA; 3 = straight line trend fitted to original data; 4 = straight line trend fitted to whole year totals. The {Trend Estimate} used when using Averages Methods 1 or 2 is provided by a moving average (MA), whose length is equal to the number of periods in a year. Most timescales have an even number of periods per year (typically months or quarters), so it is necessary to center the MA to avoid bias when the trend is not constant. The centered MA for May is the average of the two averages for (November to October) and for (December to November). Doing it this way you end up losing a whole year of actuals (six months at the beginning and six months at the end) when you have calculated the MA. With 2 to 4 years of actuals SeasonLite uses method 4, the trend through whole years, to provide the {trend estimate} to calculate factors. This means assembling as many whole year averages, as far apart from each other as possible, and fitting a straight line through them to get the {trend estimate}.

Pro Method 4 - Working Days

1 = no working day adjustment; 2 = user input working days; 3 = use calendar days as working days. SeasonLite always uses no working day adjustment. SeasonPro will remove the adjustment from actual periods, and then apply it to forecast periods. If you believe the level of your data depends on the number of days in your month, then doing this can improve the accuracy of your forecasts.

Pro Method 5 - Cycles

1 = no cycles in forecast or calculations; 2 = apply cycles to forecast; 3 = adjust for cycles in calculations and apply them to the forecast. SeasonLite always uses no cycles in forecast or calculations. Using this SeasonPro method enables you to exert considerable control over the results of calculating the factors and forecasts.

Pro Method 6 - Trend

1 = fit straight line trend through the adjusted data; 2 = fit straight line trend through the original data; 3 = constant trend = average of adjusted actual data; 4 = parabolic trend, through the adjusted data. SeasonLite prefers to use method 1, but will use method 3 when there is not much history. You get the chance to insist on any of methods 1, 3 or 4. Method 2 is the classic method, if you want it you must use SeasonPro.

532 Analyst

Chapter 12: Built in Functions (BiFs)

Messages
Below are messages and their associated text. The two types of messages come from Errors and Warnings. Errors cause the result and output variables to be set to zero in the slice where the error occurs. Warnings are issued when there is sufficient data to make the calculations, but the method you have chosen may not work well with so little data.

Errors
Message 579, too much of year missing. @SeasonLite not enough actuals in slice "Case 5" for 12 periods from "Apr-00", outputs and result will be zero at season.lite[factors]. This message appears if you have excluded too many periods as not actual between the first and last actual period. For a monthly timescale you must have at least 9 actual months in every 12 month sequence. Message 580, whole periods missing.@SeasonLite in slice "Case 2" no actuals in periods "Mar-01" "Apr-01" "May-01", outputs and result will be zero, at season.lite[factors]. This message will appear if there is a period that is not actual for all years between the first and last actual periods. The message shows the first appearance of each period.

Warnings
Message 582, you are taking the average of one number. @SeasonLite in slice "Case 21", some periods have only 1 actuals, 2 are preferred for method MA average, at season.full[seasonal factors]. For the MA average method you want at least two actuals to average for every period with in the year, you would prefer many more observations for each factor. When using the medial average method you need four actuals for each factor, so that you are averaging at least two numbers when you discard the highest and lowest values. You will see a lot of this message if you apply the moving average method to data with less than three years actuals. Message 583, not enough data to use the medial average. @SeasonLite in slice "Case 24", some periods have only 1 actuals, 3 are needed for medial average, using MA average instead, at season.full[seasonal factors].

If you don't have three actuals for every period in the year then you cannot use the medial average method. When you see this message, the results for this slice will be based on the MA average method.

@SeasonPro
Introduction
The @SeasonPro built in function performs seasonal adjustments of time to determine seasonal patterns in data. The @SeasonPro built in function has more functionality and flexibility than @SeasonLite. It is intended for the highly advanced user of statistical data. It is based on classical time series decomposition and requires at least one year of historical data.

User Guide 533

Chapter 12: Built in Functions (BiFs) SeasonLite and SeasonPro use the same programs to calculate their results, they differ only in the number of methods and input and output variables available. SeasonPro = @SeasonPro(Method; ActFlag; Original; WorkingDays; Cycle%; OverFlag; OverValue; Factor; Adjusted; MovingAverage; Ratio; Trend; Cycle; Irregular; Calculated; Diagnostics).

Name
Method

Input/Output Description
Input 1* Multiplicative, 2* Additive; *1* Medial, *2* MA, *3* Average year, *4* Typical year 1 = actual, actual periods are used to calculate the seasonal factors The data to be seasonally adjusted The working days in the period The cycle percent Override Flag Override Value The seasonal adjustment factors for your data The seasonally adjusted data Moving Average The ratio of original to MA The long term trend of the data The cyclical component The irregular component The forecast of the expected original value for every period A few simple diagnostics to evaluate the model OverValue if OverFlag = 1, Original if ActFlag = 1, otherwise Calculated

ActFlag

Input

Original WorkingDays Cycle% OverFlag OverValue Factor Adjusted MA Ratio Trend Cycle Irregular Calculated Diagnostic Forecast

Input Input Input Input Input Output Output Output Output Output Output Output Output Output Result

The output variable {Diagnostics} contains the following values, where ## refers to the period number: 534 Analyst

Chapter 12: Built in Functions (BiFs)

##
1 2 3 4 5 6 7

Holds
Trend constant Trend slope Trend change in slope spare spare Mean Percentage Error Mean Squared Error

Comments

Zero when trend method is constant Zero except for parabolic trend method

Non-zero value implies some bias Useful for statistical calculations, and for comparing different methods on the same data

Mean Absolute Percentage Useful for statistical calculations, this understandable Error measure of level of irregular component is useful for comparing relative accuracy of different methods or different slices in the cube. Non-normalized average seasonal factors See AT and NT in the Equations section

9 to P+8

Methods
There are six SeasonPro methods which are combined into a single positive integer. The method used for a slice of a cube is taken from the first period with a non-zero entry in the method input variable. Each method has a default value of 1 and may take any integer value between 1 and 9. Methods that you want to assume their default value are omitted. Any zeroes in the method are ignored. Thus method = 12, method = 121111 and method = 102 all have the same effect. Method number n uses the nth digit in your method number.

##
1

Method
Basic Method

Setting
1 = Multiplicative 2 = Additive

Average Method

1 = Medial average 2 = MA average 3 = Average year 4 = Typical year User Guide 535

Chapter 12: Built in Functions (BiFs)

##
3

Method
MA Method

Setting
1 = centered MA 2 = uncentered MA 3 = straight line trend fitted to original data 4 = straight line trend fitted to whole year totals

Working Days

1 = no working day adjustment 2 = user input working days 3 = use calendar days as working days

Cycles

1 = no cycles in forecast or calculations 2 = apply cycles to forecast 3 = adjust for cycles in calculations and apply them to the forecast

Trend

1 = fit straight line trend through the adjusted data 2 = fit straight line trend through the original data 3 = constant trend = average of adjusted actual data 4 = parabolic trend, through the adjusted data

The average method applies when calculating the average seasonal factor from all the {ratios} = 100 * {original} / {MA}. Medial means drop the highest and lowest ratio before taking the average, MA means use all the ratios in the average. The centered and uncentered options only differ when the number of periods in a year is even. This is common because monthly or quarterly time scales are the norm. Whole year totals means the first actual year, the last actual year, and as many other non-overlapping whole years you can fit in between them.

Multiplicative Model
The multiplicative model is O = T*C*S*I*W, where O = Original data, T = Trend, C = Cycle, S = Seasonal, I = Irregular, and W = working day effect. It applies when method[1] = 1, the steps in the calculations are:

Steps
1. Calculate HP the half periodicity of the time scale as the integer part of (P-1)/2, where P is the periodicity of the time scale (the number of periods in a year). 2. Set N = total number of periods in the time scale.

536 Analyst

Chapter 12: Built in Functions (BiFs) 3. For all periods calculate W, the working day effect. W = 1 if method[4] = 1, otherwise W = N * D / SUMD, where D is the number of days in each period and SUMD is the sum of D over all periods. 4. Calculate for all actual periods U = O / W. 5. Calculate C the cycle effect as a percentage, where 100 = no effect. for method[5] = 1, C = 100 everywhere; for method[5] = 2, C =100 in actual periods, {Cycle%} elsewhere; for method[5] = 3, C = {Cycle%} everywhere. 6. Calculate for actual periods U = 100 * U / C. U now represents the original data to use after adjusting for the working day effect and any known, user defined cyclical effects. 7. Calculate MA, the estimated combined Trend and Cycle effects. It is called MA because it is traditionally estimated by a moving average. The equation steps described from here on only apply when method[2] is 1 or 2. If method[3] = 1 or 2 then MAT = SUMU / SUMP where SUMU is the sum of U for actual periods from period T - HP to T + P - (HP + 1), where T is the period for which MA is being calculated. This means, for example, that in a monthly timescale SUMU for January is the sum of U from the previous July to the next June. SUMP is the number of actual periods contributing to SUMU, typically it is P, unless the user is excluding some historical periods from the analysis by flagging them as not actual. No value for MAT is calculated for the first HP actual periods and the last P-(HP+1) periods. In a monthly time scale the first 6 months and last five months of actual periods have zero MA. If method[3] = 3 then MA is the straight line fitted through all the actual periods. If method[3] = 4 then MA is the straight line fitted through whole year totals the actual periods. 8. If P is even and method[3] = 1 center MA by calculating

MA T = (MA T + MA(T-1) ) / 2
MA is now missing the first and last (HP+1) = (P/2) periods. This is the output variable {MA} . 9. For all those actual periods where MA has been calculated the ratio R is calculated as R = 100 * U / MA. This is the output variable {Ratio}. 10. For each of the calendar periods 1 to P, average the corresponding values of R. When using method[2] = 1 (the medial method) for each period averaged, dispose of the highest and lowest values of R before calculating the average. These averages

AT
where T goes from 1 to P, are the outputs in periods 9 to P+8 in the {Diagnostics} output variable, organized so the first factor in diagnostics[9] applies to the first actual period. 11. Normalize the average seasonal factors so they add to P.

NT = P * A T /SUMA
User Guide 537

Chapter 12: Built in Functions (BiFs) where SUMA is the sum over all P of the

AT
12. Replicate the

NT
over all periods to give the output variable {Factors}. 13. Calculate {Adjusted} = 100 * {Original} / {Factors} for all actual periods. 14. Calculate {Trend} as the straight line through: {Original} if method[6] = 1 {Adjusted} if method[6] = 2 This is done for all actual periods and takes the form {Trend} = A + B * T+C*T^2, where T = 1 corresponds to the first period in the timescale. {A}, the constant, {B}, the slope, and {C}, the change in slope, are stored in periods 1-3 of the output variable {Diagnostics}. {B} and {C} are zero if method[6]=3 for constant and {C} is zero in method[6] = 1 or 2 for linear. 15. Calculate {CI}, the combined cycle and irregular components, {CI} = 100 * {U} / ({Trend} * {Factors} / 100) for all periods for which {MA} is calculated. 16. Calculate {Cperiods}, the length of the moving average to apply to CI to isolate the Cyclical part. It is the first odd number of periods greater than or equal to half a year (typically 7 months, or 3 quarters) 17. Cycle} = the {Cperiods} moving average of {CI}. {Cycle) is shorter than {CI}, losing ({Cperiods} -1)/2 periods at each end, typically 3 months or 1 quarter. If there are gaps in your actuals, the technique described in equation (7) above modifies the calculations to handle the periods that are excluded from the actuals. 18. Irregular} = 100 * {CI} / {Cycle}, for all the periods in which {Cycle} is calculated. 19. For all periods calculate F = {Trend} * {Factors} /100. This is the forecast before factoring in future working day and user cycle adjustments. 20. For all periods calculate {Forecast} depending on method[5]: if method[5] =1 {Forecast} = W * F If method[5] = 2 or 3 {Forecast} = W * F * C / 100 21. Calculate the error diagnostics: {n} = the number of actual periods. {error} = U - F for all actual periods. {pcerror} = 100 * {error} / U {mpe} = mean percentage error = SUMP / {n}, where SUMP is the sum of {pcerror} over all actual periods.

538 Analyst

Chapter 12: Built in Functions (BiFs) {mse} = mean squared error = SUMS / {n}, where SUMS is the sum of {error}^2 over all actual periods. {mape} = mean absolute percentage error = SUMA / {n}, where SUMA is the sum of the absolute value of {pcerror} over all actual periods. {mpe}, {mse} and {mape} go into periods 6 to 8 in the output variable {Diagnostics}.

Additive Model
The additive model is O = W * (T+C+S+I), it applies when method[1] = 2. The places where the additive model equations differ from the multiplicative model equations are shown in this table

##
5 6 9 11 13 15 18 19 20

Multiplicative
C = 100 U = 100 * U / C R = 100 * U / MA
NT = 12 * AT /SUMA

Additive
C=0 U=U-C R = U - MA
NT = A T -SUMA

{Adjusted} = 100 * {Original} / {Factors} {CI} = 100 * {U} / ({Trend}* {Factors} / 100) {Irregular} = 100 * {CI} / {Cycle} F = {Trend} * {Factors} /100 {Forecast} = W * F * C / 100

{Adjusted} = {Original} - {Factors} {CI} = {U} - ({Trend} + {Factors}) {Irregular} = {CI} - {Cycle} F = {Trend} + {Factors} {Forecast} = W * (F + C)

Whole Year Totals

This describes which years to total when method[3] = 4.

Steps
1. Calculate AP, the number of periods between the first and last actual periods (including both ends). 2. Calculate Y, the number of whole years, as the integer part of AP / P, where P = number of periods in a year. 3. Calculate GP, the total number of periods in the gaps between each year, as GP = AP - Y * P. 4. Calculate AGP, the average gap length, as GP / (Y-1).

User Guide 539

Chapter 12: Built in Functions (BiFs) 5. Calculate CGP, the cumulative gap between successive years, as the integer part of the cumulative sum of a vector of length (Y-1) with each value = AGP. This means the first whole year is the first P actuals, the last whole year is the last P actuals, and the length of the gaps between any intervening years will be either the integer part of AGP, or one period longer. If any periods between the first and last actuals are excluded, they will be excluded from the whole year total, but not from the gap calculations.

Basic Examples
Each of the following examples have been created using 5 years of actual data and then using the SeasonPro BiF to forecast for a further 2 years. The models are all of the multiplicative type and therefore option 1 should always be selected for the Basic Method. As 5 years of historic data are utilized with consistent seasonal and cyclical factors then option 1 is most appropriate for Method 2 - Average and Method 3 - MA. The actual data has been created by combining a trend with seasonal/cyclical factors and a working day effect. The following examples increase in complexity from a linear trend to a parabolic trend with seasonality.

Example 1: Linear Growth

The trend increases from a base of 100 by 2 each month, a line with the formula y=100+2x(Period No-1)

Actual Data
1999 Trend Seasonality Working Days

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100 0 0

102 0 0

104 0 0

106 0 0

108 0 0

110 0 0

112 0 0

114 0 0

116 0 0

118 0 0

120 0 0

122 0 0

Random 0 Adjustment 2000 Trend Seasonality 124 0

126 0

128 0

130 0

132 0

134 0

136 0

138 0

140 0

142 0

144 0

146 0

540 Analyst

Chapter 12: Built in Functions (BiFs)

Actual Data
Working Days

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

Random 0 Adjustment 2001 Trend Seasonality Working Days 148 0 0

150 0 0

152 0 0

154 0 0

156 0 0

158 0 0

160 0 0

162 0 0

164 0 0

166 0 0

168 0 0

170 0 0

Random 0 Adjustment 2002 Trend Seasonality Working Days 172 0 0

174 0 0

176 0 0

178 0 0

180 0 0

182 0 0

184 0 0

186 0 0

188 0 0

190 0 0

192 0 0

194 0 0

Random 0 Adjustment 2003 Trend Seasonality Working Days 196 0 0

198 0 0

200 0 0

202 0 0

204 0 0

206 0 0

208 0 0

210 0 0

212 0 0

214 0 0

216 0 0

218 0 0

Random 0 Adjustment

User Guide 541

Chapter 12: Built in Functions (BiFs) As the data is linear then the key variable from SeasonPro to consider is Method 6; the trend and option 1 would give the required result. Utilizing the Method 111111 gives the following result:

Key
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The trend value shows the values calculated using the formula for the straight line; the Season Pro BiF line shows the actual data for years 1 through 5 and the forecast values that have been calculated for years 6 and 7.

Example 2: Parabolic Growth

The trend increases from a base of 100 by 2 times the square of the month, which is a line with the formula y=100+2x(Period No-1)^2

Actual Data Jan

1999 Trend Seasonality Working Days Random Adjustment 2000 100 0 0

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

106 0 0

116 0 0

130 0 0

148 0 0

170 0 0

196 0 0

226 0 0

260 0 0

298 0 0

340 0 0

386 0 0

542 Analyst

Chapter 12: Built in Functions (BiFs)

Actual Data Jan

Trend Seasonality Working Days Random Adjustment 2001 Trend Seasonality Working Days Random Adjustment 2002 Trend Seasonality Working Days Random Adjustment 2003 Trend Seasonality Working Days 436 0 0

Feb
490 0 0

Mar Apr
548 0 0 610 0 0

May Jun
676 0 0 746 0 0

Jul
820 0 0

Aug Sep
898 0 0 980 0 0

Oct

Nov Dec

1066 1156 1250 0 0 0 0 0 0

1348 1450 1556 1666 1780 1898 2020 2146 2276 2410 2548 2690 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

2836 2986 3140 3298 3460 3626 3796 3970 4148 4330 4516 4706 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

4900 5098 5300 5506 5716 5930 6148 6370 6596 6826 7060 7298 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

User Guide 543

Chapter 12: Built in Functions (BiFs)

Actual Data Jan

Random Adjustment 0

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

As the data is parabolic then the key variable from SeasonPro to consider is Method 6; the trend in this case option 4 would give the required result. Utilizing the Method 111114 gives the following result:

Key:
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The trend value shows the values calculated using the formula for the parabolic curve; the Season Pro BiF line shows the actual data for years 1 through 5 and the forecast values that have been calculated for years 6 and 7. As a comparison utilizing the Method 111111 causes the best straight line to be forecast for the future months giving the following result:

Key:
Trend = White

544 Analyst

Chapter 12: Built in Functions (BiFs) Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The trend value shows the values calculated using the formula for the parabolic curve; the Season Pro BiF line shows the actual data for years 1 through 5 and the forecast values that have been calculated for years 6 and 7, in this case the forecast years are calculated assuming that the actual data fits a linear trend.

Example 3: Linear Growth plus Seasonality

The trend increases from a base of 100 by 2 each month i.e. a line with the formula y=100+2x (Period No-1) a seasonal factor is then applied to adjust the results across the months.

Seasonal Factors
Factors

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100

100

150

150

100

75

50

50

75

100

150

200

Combining the trend with the Seasonal Factor gives the following actual data:

Actual Data Jan

1999 Trend Seasonality Working Days Random Adjustment 2000 Trend Seasonality Working Days 124 0 0 100 0 0

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

102 0 0

104 52 0

106 53 0

108 0 0

110 (28) 0

112 (56) 0

114 (57) 0

116 (29) 0

118 0 0

120 60 0

122 122 0

126 0 0

128 64 0

130 65 0

132 0 0

134 (34) 0

136 (68) 0

138 (69) 0

140 (35) 0

142 0 0

144 72 0

146 146 0

User Guide 545

Chapter 12: Built in Functions (BiFs)

Actual Data Jan

Random Adjustment 2001 Trend Seasonality Working Days Random Adjustment 2002 Trend Seasonality Working Days Random Adjustment 2003 Trend Seasonality Working Days Random Adjustment 196 0 0 172 0 0 148 0 0 0

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

150 0 0

152 76 0

154 77 0

156 0 0

158 (40) 0

160 (80) 0

162 (81) 0

164 (41) 0

166 0 0

168 84 0

170 170 0

174 0 0

176 88 0

178 89 0

180 0 0

182 (46) 0

184 (92) 0

186 (93) 0

188 (47) 0

190 0 0

192 96 0

194 194 0

198 0 0

200 100 0

202 101 0

204 0 0

206 (52) 0

208

210

212

214 0 0

216 108 0

218 218 0

(104) (105) (53) 0 0 0

As the data is linear then the key variable from SeasonPro to consider is Method 6; the trend and option 1 would give the required result. With option 1 the linear trend is calculated on the data that has been adjusted for the seasonality. Utilizing the Method 111111 gives the following result:

546 Analyst

Chapter 12: Built in Functions (BiFs)

Key:
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The impact of the seasonality can be seen as the linear trend is adjusted by the value of the seasonality to give the actual data, years 1 through 5, and forecast data, years 6 and 7, as calculated using the formula. The Season Pro BiF line shows actuals for years 1 through 5 and the forecast value calculated by the BiF for years 6 and 7.

Example 4: Linear Growth plus Complex Seasonality

The trend increases from a base of 100 by 2 each month i.e. a line with the formula y=100+2x (Period No-1) a seasonal factor is then applied to adjust the results across the months. The seasonal factors are calculated using the Cycles BiF with 2 degrees of freedom and amplitudes of 80 and 60; this gives rise to the following seasonal factors:

Seasonal Factors
Factors

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100

96

80

56

30

10

20

44

70

90

Combining the trend with the Seasonal Factor gives the following actual data:

Actual Data Jan

1999 Trend Seasonality 100 (0)

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

102 (4)

104 (21)

106 (47)

108 (75)

110 (99)

112

114

116

118 (66)

120 (36)

122 (12)

(112) (109) (93)

User Guide 547

Chapter 12: Built in Functions (BiFs)

Actual Data Jan

Working Days Random Adjustment 2000 Trend Seasonality Working Days Random Adjustment 2001 Trend Seasonality Working Days Random Adjustment 2002 Trend Seasonality Working Days Random Adjustment 2003 172 (1) 0 148 (1) 0 124 (0) 0 0

Feb
0

Mar Apr
0 0

May Jun
0 0

Jul
0

Aug Sep
0 0

Oct
0

Nov Dec
0 0

126 (5) 0

128 (26) 0

130 (57) 0

132 (92) 0

134

136

138

140

142

144 (44) 0

146 (15) 0

(121) (136) (132) (112) (79) 0 0 0 0 0

150 (6) 0

152 (30) 0

154 (68) 0

156

158

160

162

164

166

168 (51) 0

170 (17) 0

(109) (142) (159) (155) (131) (93) 0 0 0 0 0 0

174 (7) 0

176 (35) 0

178 (78) 0

180

182

184

186

188

190

192

194 (19) 0

(125) (164) (183) (179) (150) (106) (58) 0 0 0 0 0 0 0

548 Analyst

Chapter 12: Built in Functions (BiFs)

Actual Data Jan

Trend Seasonality Working Days Random Adjustment 196 (1) 0

Feb
198 (8) 0

Mar Apr
200 (40) 0 202 (89) 0

May Jun
204 206

Jul
208

Aug Sep
210 212

Oct
214

Nov Dec
216 218 (22) 0

(142) (185) (207) (202) (170) (120) (66) 0 0 0 0 0 0 0

In this case the underlying tend is linear and the trend should be forecast utilizing the data that has been adjusted for the seasonality, option 1 should therefore be chosen for Method 6. Utilizing the Method 111111 gives the following result:

Key:
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The impact of the seasonality can be seen as the linear trend is adjusted by the value of the seasonality to give the actual data, years 1 through 5, and forecast data, years 6 and 7, as calculated using the formula. The Season Pro BiF line shows actuals for years 1 through 5 and the forecast value calculated by the BiF for years 6 and 7.

Example 5: Parabolic Growth plus Seasonality

The trend increases from a base of 100 by 2 times the square of the month i.e. a line with the formula y=100+2x(Period No-1)^2 a seasonal factor is then applied to adjust the results across the months.

User Guide 549

Chapter 12: Built in Functions (BiFs)

Seasonal Factors
Factors

Jan

Feb

Mar Apr

May Jun

Jul

Aug

Sep

Oct

Nov Dec

100

100

150

150

100

75

50

50

75

100

150

200

Combining the trend with the Seasonal Factor gives the following actual data:

Actual Data
1999 Trend Seasonality Working Days

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

100 0 0

106 0 0

116 58 0

130 65 0

148 0 0

170 (43) 0

196 (98) 0

226 (113) 0

260 (65) 0

298 0 0

340 170 0

386 386 0

Random 0 Adjustment 2000 Trend Seasonality Working Days 436 0 0

490 0 0

548 274 0

610 305 0

676 0 0

746 (187) 0

820 (410) 0

898 (449) 0

980 (245) 0

1066 0 0

1156 578 0

1250 1250 0

Random 0 Adjustment 2001 Trend Seasonality Working Days 1348 0 0

1450 0 0

1556 778 0

1666 833 0

1780 0 0

1898 (475) 0

2020

2146

2276

2410 0 0

2548 1274 0

2690 2690 0

(1010) (1073) (569) 0 0 0

Random 0 Adjustment

550 Analyst

Chapter 12: Built in Functions (BiFs)

Actual Data
2002 Trend Seasonality Working Days

Jan

Feb

Mar

Apr

May

Jun

Jul

Aug

Sep

Oct

Nov

Dec

2836 0 0

2986 0 0

3140 1570 0

3298 1649 0

3460 0 0

3626 (907) 0

3796

3970

4148

4330

4516 2258 0

4706 4706 0

(1898) (1985) (1037) 0 0 0 0 0

Random 0 Adjustment 2003 Trend Seasonality Working Days 4900 0 0

5098 0 0

5300 2650 0

5506 2753 0

5716 0 0

5930

6148

6370

6596

6826

7060 3530 0

7298 7298 0

(1483) (3074) (3185) (1649) 0 0 0 0 0 0

Random 0 Adjustment

As the trend data is parabolic then the key variable from SeasonPro to consider is Method 6; the trend and option 4 would give the required result. Utilizing the Method 111114 gives the following result:

Key:
Trend = White Seasonality = Green Working Days = Grey User Guide 551

Chapter 12: Built in Functions (BiFs) Random Adjustment = Orange Season Pro BiF = Blue

The impact of the seasonality can be seen as the linear trend is adjusted by the value of the seasonality to give the actual data, years 1 through 5, and forecast data, years 6 and 7, as calculated using the formula. The Season Pro BiF line shows actuals for years 1 through 5 and the forecast value calculated by the BiF for years 6 and 7.

Example 6: Linear Growth plus Complex Seasonality utilizing Cycles

The base data here is the same in example 4 apart from the inclusion of a random adjustment to the data and that the cycles option is then utilized within the BiF. The trend increases from a base of 100 by 2 each month i.e. a line with the formula y=100+2x (Period No-1) a seasonal factor is then applied to adjust the results across the months. The seasonal factors are calculated using the Cycles BiF with 2 degrees of freedom and amplitudes of 80 and 60; this gives rise to the following seasonal factors:

Seasonal Factors
Factors

Jan Feb Mar Apr May Jun

Jul

Aug Sep

Oct

Nov Dec

100 96

80

56

30

10

20

44

70

90

Combining the trend with the Seasonal Factor and the random adjustment gives the following actual data:

Actual Data
1999 Trend Seasonality Working Days

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100 (0) 0

102 (4) 0

104 (21) 0

106 (47) 0

108 (75) 0

110 (99) 0

112

114

116

118 (66) 0

120 (36) 0

122 (12) 0

(112) (109) (93) 0 0 0

Random 14 Adjustment 2000 Trend Seasonality 124 (0)

40

26

40

33

47

44

33

25

11

126 (5)

128 (26)

130 (57)

132 (92)

134

136

138

140

142

144 (44)

146 (15)

(121) (136) (132) (112) (79)

552 Analyst

Chapter 12: Built in Functions (BiFs)

Actual Data
Working Days

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

Random 29 Adjustment 2001 Trend Seasonality Working Days 148 (1) 0

28

17

37

41

14

32

45

150 (6) 0

152 (30) 0

154 (68) 0

156

158

160

162

164

166

168 (51) 0

170 (17) 0

(109) (142) (159) (155) (131) (93) 0 0 0 0 0 0

Random 32 Adjustment 2002 Trend Seasonality Working Days 172 (1) 0

14

40

27

19

34

24

44

24

29

33

174 (7) 0

176 (35) 0

178 (78) 0

180

182

184

186

188

190

192

194 (19) 0

(125) (164) (183) (179) (150) (106) (58) 0 0 0 0 0 0 0

Random 35 Adjustment 2003 Trend Seasonality Working Days 196 (1) 0

28

31

34

41

24

48

11

17

12

45

24

198 (8) 0

200 (40) 0

202 (89) 0

204

206

208

210

212

214

216

218 (22) 0

(142) (185) (207) (202) (170) (120) (66) 0 0 0 0 0 0 0

Random 2 Adjustment

18

34

22

15

15

32

15

30

50

20

User Guide 553

Chapter 12: Built in Functions (BiFs) In this case the underlying trend is linear and the trend should be forecast utilizing the data that has been adjusted for the seasonality, option 1 should therefore be chosen for Method 6. Where the cycle pattern is known or can be approximated then Method 5 will enable the forecast to be refined by either using option 2 to apply a defined cycle to the forecast or using option 3 to adjust the actual data for the cycle and apply the defined cycle to the forecast. Utilizing the Method 111131, adjusting the actual and forecast for the defined cycles, gives the following result:

Key:
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The impact of the seasonality and random adjustment can be seen as the linear trend is adjusted by the value of the seasonality and random value to give the actual data, years 1 through 5, and forecast data, years 6 and 7, as calculated using the formula. The Season Pro BiF line shows actuals for years 1 through 5 and the forecast value calculated by the BiF for years 6 and 7, and using the defined cycle for the calculation of the forecast numbers.

Example 7: Linear Growth plus Seasonality and incorporating Working Days

The trend increases from a base of 100 by 2 each month, a line with the formula y=100+2x(Period No-1) a seasonal factor is then applied to adjust the results across the months. The results are then further adjusted for the number of working days within each month.

Seasonal Factors
Factors

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100

100

150

150

100

75

50

50

75

100

150

200

554 Analyst

Chapter 12: Built in Functions (BiFs)

Working Jan Days

Days 10

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

20

20

10

20

20

10

10

20

20

20

10

Combining the trend with the Seasonal Factor and Working days adjustment gives the following actual data:

Actual Data
1999 Trend Seasonality Working Days

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

100 0 (37)

102 0 27

104 52 41

106 53 (59)

108 0 28

110 (28) 22

112 (56) (21)

114 (57) (21)

116 (29) 23

118 0 31

120 60 47

122 122 (90)

Random 0 Adjustment 2000 Trend Seasonality Working Days 124 0 (46)

126 0 33

128 64 51

130 65 (72)

132 0 35

134 (34) 26

136 (68) (25)

138 (69) (25)

140 (35) 28

142 0 37

144 72 57

146 146 (108)

Random 0 Adjustment 2001 Trend Seasonality Working Days 148 0 (55)

150 0 39

152 76 60

154 77 (85)

156 0 41

158 (40) 31

160 (80) (29)

162 (81) (30)

164 (41) 32

166 0 44

168 84 66

170 170 (125)

User Guide 555

Chapter 12: Built in Functions (BiFs)

Actual Data

Jan

Feb

Mar Apr

May Jun

Jul

Aug Sep

Oct

Nov Dec

Random 0 Adjustment 2002 Trend Seasonality Working Days 172 0 (63)

174 0 46

176 88 69

178 89 (98)

180 0 47

182 (46) 36

184 (92) (34)

186 (93) (34)

188 (47) 37

190 0 50

192 96 76

194 194 (143)

Random 0 Adjustment 2003 Trend Seasonality Working Days 196 0 (72)

198 0 52

200 100 79

202 101

204 0

206 (52) 41

208

210

212

214 0 56

216 108 85

218 218 (161)

(104) (105) (53) (38) (39) 42

(112) 54

Random 0 Adjustment

In this case the underlying tend is straight line and the trend should be forecast utilizing the data that has been adjusted for the seasonality, option 1 should therefore be chosen for Method 6. Where the number of working days are known the impact of this can be used to adjust the data. Method 4 will adjust the actual data for the working days and then apply an adjustment to the forecast. Option 2 is used where the working days are manually input, option 3 will utilize the calendar days. Utilizing the Method 111211, adjusting the actual and forecast for the number of working days, gives the following result:

556 Analyst

Chapter 12: Built in Functions (BiFs)

Key:
Trend = White Seasonality = Green Working Days = Grey Random Adjustment = Orange Season Pro BiF = Blue

The impact of the seasonality working days can be seen as the straight line trend is adjusted by the value of the seasonality and the value of the working days adjustment to give the actual data, years 1 through 5, and forecast data, years 6 and 7, as calculated using the formula. The Season Pro BiF line shows actuals for years 1 through 5 and the forecast value calculated by the BiF for years 6 and 7, and incorporates the number of working days into the calculation of the forecast numbers.

Advanced Examples
In the sample cube liteq in report lite the original data in slice one is an exact representation of the formula O = T * S / 100 where T is a trend that increases by 2 each quarter and S is four seasonal factors. S is the same for all years, taking the values of 50 in Q1, 100 in Q2 and Q3 and 150 in Q4. This table explores how season has coped with this data using the method multiplicative, medial average method. The following table has the first 3 years of quarters as the rows; the columns are: 1 2 3 4 5 6 The trend used to calculate the original data. The seasonal percentage factors used to calculate the original data. The original data. The first uncentered MA. The centered MA. The ratios.

User Guide 557

Chapter 12: Built in Functions (BiFs)

The factors (compare with column 2)

1
12 14 16 18 20 22 24 26 28 30 32 34

2
50 100 100 150 50 100 100 150 50 100 100 150

3
6 14 16 27 10 22 24 39 14 30 32 51

7
50.36 99.32

15.75 16.75 18.75 20.75 23.75 24.75 26.75 28.75 31.75 32.75

16.25 17.75 19.75 22.75 24.25 25.75 27.75 30.25 32.25 33.75

98.46 152.11 50.63 98.88 98.97 151.46 50.45 99.17 99.22 151.11

98.18 151.14 50.36 99.32 98.18 151.14 50.36 99.32 98.18 151.14

The uncentered MA (column 4) loses the first two quarters and the last quarter (not shown here) of the actual periods. When you center it (column 5) you lose an extra quarter at the end, so there are two missing from the beginning and from the end. The centered moving average gets reasonably close to the known trend. It can never get exactly on it, unless the trend slope is zero, or the seasonal factors are flat. This explains why the estimated seasonal factors are a bit different to the known factors (by about 0.75% on average). You can see by studying the table of ratios below that the key factor influencing how close you will get is the trend growth expressed as a percentage of the trend level. In this example in 2000 Q1 the growth is two on a value of 10 (or 20% per quarter). By 2005 Q4 it is a growth of 2 on a value of 58 (less than 2% per quarter) and you can see that by 2004/5 the ratios are 1% closer to their known values than in 2000/1. In more complex methods, like X-11, there is a second phase of calculation where the preliminary adjusted data from this first phase are used to make more refined estimates of the factors. This requires much more calculation and needs more history. This table shows how the ratios are used to calculate the average seasonal factors:

558 Analyst

Chapter 12: Built in Functions (BiFs)

Q3
2000/1 2001/2 2002/3 2003/4 2004/5 Average Medial Average Normalized Medial 98.46 98.97 99.22 99.38 99.48 99.10 99.19 99.18

Q4
152.11 151.46 151.11 150.90 150.75 151.27 151.16 151.14

Q1
50.63 50.45 50.35 50.29 50.24 50.39 50.36 50.36

Q2
98.88 99.17 99.35 99.46 99.54 99.28 99.33 99.32

Total
400.08 400.05 400.03 400.02 400.02 400.04 400.03 400.00

Diagnostics, for slices one and thirteen of cube liteq, are: Variable Trend Constant Trend Slope Mean percentage error Mean squared error Mean absolute percentage error one 7.326 2.274 0.45 5.35 5.58 thirteen 10.005 2.000 -0.009 0.098 0.744

Slice thirteen is the same as slice one, except that the trend is fitted through the adjusted data, rather than the original data. You can see that because the data starts with Q1, which has a low factor, and ends with Q4, which has a high factor, the slope is overestimated in one and spot on in thirteen. This is a convincing argument for making fit to adjusted the default setting for the trend calculation, which it now is. In thirteen we get an average absolute error of about three-quarters of a percent for this sample data, where the slope of 2 is quite steep from a base of 10 and the difference in the seasonal factors is quite high (50 to 150).

User Cycles
Case 5 of the cube full in report full fits a multiplicative, medial model with the trend going through the adjusted data to the car accident data used in Makridakis and Wheelwright. The CI graph in the report looks like this:

User Guide 559

Chapter 12: Built in Functions (BiFs)

The {Cycle} line is the combined cycle and irregular components left after fitting the model. The {Cycle Factors} line is a six year sine wave with a suitable amplitude calculated in the cube transform and linked into full. In Case 5 method[5] = 1, so these factors are not used in calculating {Cycle}. In Case 8 however I have set method[5] = 3, so the {Cycle Factors} are used both to calculate the seasonal factors and to forecast the future. The resulting {Cycle} are shown in this graph. Now {Cycle} show less sign of having a long term cycle, but it is still dominated by the eleven months ending with Mar 04 where {Cycle} drops each month and the subsequent more erratic behavior.

The diagnostics in each case look like this: Variable Constant Slope {mpe} {mse} {mape} Case 5 33.03 (0.05) (0.30) 2.75 4.44 Case 8 32.19 (0.03) (0.18) 1.72 3.47

Not surprisingly, the diagnostic error values are less in Case 8 than in Case 5, the mean error of forecasts against the actual reduces from around 4.5% to 3.5%. If you used method[5]=3 to remove your view of the cycle component, you would be hoping to see no sign of any long term cycles in the resulting {Cycle} output. Case 8 does not necessarily represent a more accurate forecast. The apparent cyclical behavior seen in Case 5 may indeed be real, and its frequency is about what you would expect if it were driven by a typical economic cycle. More years of data might give more accurate results. A linear trend

560 Analyst

Chapter 12: Built in Functions (BiFs) may not be a good fit for this data, as you would want to understand what happened between March 2003 and Mar 2004 to make {Cycle} drop continuously. SeasonPro offers a simple model that is easy enough to understand - method[5] gives you an easy way understand the behavior of your data, both when analyzing history and forecasting the future. The fact that your inputs reduce the diagnostic errors should not be used as evidence that the new forecast are more statistically valid and accurate. Although the input variable {Cycle%} is described as addressing the cyclical effects, you can use it in anyway you like to modify both the influence an actual period has on the analysis and the forecast for any period. It is a powerful tool that should be used with care. Nevertheless, if you are forecasting a series with little history and you believe you have a good idea of the long term cycle it might follow, then you can use method[5] to make your forecast reflect your judgements.

The Different Methods

The data used in this example is typical of the forecasting situations which SeasonPro is designed to help. There are only 27 months of history to work with. The table, which shows the seasonal factors and the main diagnostics, reviews eight different method combinations applied to the sample data:

Example 1
Cube Slice Method Jan Feb March April May June July Aug Sept Oct Full 19 123112 137.57 95.47 95.05 94.96 94.77 89.38 86.63 83.34 91.92 92.45

2
Full 20 123 137.57 95.47 95.05 94.96 94.77 89.38 86.63 83.34 91.92 92.45

3
Full 21 12 134.95 92.48 94.13 93.96 94.88 90.95 86.3 83.02 91.98 92.92

4
Full 22 13 115.64 83.21 85.68 86.06 89.12 87.11 87.37 86.85 98.87 102.55

5
Full 23 14 131.27 94.63 97.18 82.58 85.52 83.76 84.05 83.46 94.63 98.16

6
Full2 19 124 136.51 95.09 94.96 93.95 94.09 89.04 86.57 83.51 92.31 93.07

7
Full2 6 131113 115.64 83.21 85.68 86.06 89.12 87.11 87.37 86.85 98.87 102.55

8
Full2 7 141113 131.27 94.63 97.18 82.58 85.52 83.76 84.05 83.46 94.63 98.16

User Guide 561

Chapter 12: Built in Functions (BiFs)

Example 1
Nov Dec 91.71 146.76

2
91.71 146.76 101.8 4.88 0.00 10.38 1.5

3
92.91 151.51 101.56 4.87 0.02 14.12 1.67

4
104.82 172.71 105.53 4.76 (0.84) 475.74 9.02

5
100.21 164.57 107.06 4.51 (0.35) 138.79 5.18

6
92.53 148.37 101.5 4.85 0.01 7.45 1.35

7
104.82 172.71 233.13 0 (12.24) 5570.4 31.07

8
100.21 164.57 170.14 0 (4.93) 1431.2 20.66

Constant 96.6 Slope {mpe} {mse} {mape} 5.36 0.85 36.62 2.56

Examples 2 and 3 are the two methods requested by the owner of the data, and example 6 gives the best fit (lowest mean absolute percentage error). The other examples could be the best on other data, below is the data they might suit: Example 1 calculates the final trend used to do the error analysis by fitting a line through the original data. This final trend is inappropriate, so look at example 2 to assess this method. Example 2 estimates the seasonal factors by comparing original data to a linear trend fitted through the original data. It gives good results, better than example 3, but not as good as example 6. Its weakness is that, because the end of the year has the higher seasonal factors, the trend fitted through the original data (compare {constant} and {slope} in examples 1 and 2) is not close to the true trend, which distorts the estimated seasonal factors. Example 3 compares a centered 12 month moving average to the original data to get the seasonal factor estimates. The weakness of this method is caused by only having 27 months history, calculating the moving average removes 12 of the months, so you are estimating the 12 factors from only 15 ratios. I would choose this method as my first to try with three to five years history, or if I suspected the underlying trend was not a straight line. With more than five years history I would look at the medial moving average method first. Example 4 is the average year method. This would be appropriate if you believe that there is no trend behind your data, so the annual totals vary at random and the amount of each year that goes into each month is expected to be constant in the long term. These assumptions do not fit his data well, the evaluation of the errors against these assumptions would be better done against a flat trend with no slope, as in example 7. Example 5 is the typical year method. It differs from the average year method in the weight given to each year (larger years get more weight), see below for details of the average year and typical year calculations. Example 6 uses the whole year trend method, which is where the original data is compared to a trend going through the first whole year, the last whole year, and any other whole years in

562 Analyst

Chapter 12: Built in Functions (BiFs) between. For this data the trend is the line joining the first 12 months to the last 12 months (using the average placed at the center of each year). This is the method that gives the lowest {mape} for this example, and would normally be the first method to examine if there are less than two or three years of actuals. Example 7 is the average year method, evaluated against a constant final trend. For this data this is not better than example 4 because the year on year increase in the data is very marked although we would normally require more history to be confident about this. Example 8 is the typical year method, evaluated against a constant final trend. Just as example 7 has higher errors than example 4, so this example is less accurate than example 5.

Average year calculations

An example based on slice Case 22 of the sample cube full (method = 131112).

Data
Year Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Year

{U}
1 150 108 112 115 119 115 115 115 134 139 143 240

{U}
2 220 155 162 166 172 170 171 169 188 195 198 320

{U}
3 300 220 222 0 0 0 0 0 0 0 0 0 247.33

{Ratio}
1 112.15 80.75 83.74 85.98 88.97 85.98 85.98 85.98 100.19 103.93 106.92 179.44

{Ratio}
2 115.49 81.36 85.04 87.14 85.04 89.24 89.76 88.71 98.69 102.36 103.94 167.98

{Ratio}
3 121.29 88.95 89.76

Sum
*

###
*

{A T }

{N T }

* 116.31 83.69 86.18 86.56 89.63 87.61 87.87 87.35 99.44 103.14 105.43 173.71 1206.91

* 115.64 83.21 85.68 86.06 89.12 87.11 87.37 86.85 98.87 102.55 104.82 172.71 1200.00

348.93 3 252.06 3 258.54 3 173.12 2 179.26 2 175.22 2 175.75 2 174.70 2 198.87 2 206.29 2 210.85 2

93.07

347.42 2

133.75 190.5

User Guide 563

Chapter 12: Built in Functions (BiFs) This describes the equations for the multiplicative model, they replace equations (7) to (10) in Multiplicative Model Equations above: (7) For each year with actual periods: {avg} = (sum of {U} in actual periods)/ (number of actual periods in year). (8) For each actual period: {ratio} = 100 * {U} / {avg}. (9) For each calendar month: {sum} = {sum of ratios in that month}. (10) For each calendar month: {count} = {number of actual periods in that month}. (11) For each calendar month: {AT} = {sum} / {count}. (12) For each actual period {MA} is set to the {avg} for its year. For the additive model equation (8) is {ratio} = {U} - {avg}. This method expects a small number of whole years input. It is mainly designed to replicate a seasonal pattern throughout the timescale, starting with a convenient year or two of data. It does honor any actuals you wish to omit. It also makes the forecast and error calculations, but they are not very accurate. There are further examples of this method in sample cube full2 slices 9 and 22.

Typical year calculations

An example based on slice Case 23 of the sample cube full (method = 141112).

Data
Year Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov 564 Analyst

{U}
1 150 108 112 115 119 115 115 115 134 139 143

{U}
2 220 155 162 166 172 170 171 169 188 195 198

{U}
3 300 220 222 0 0 0 0 0 0 0 0

Sum
* 670 483 496 281 291 285 286 284 322 334 341

###
* 3 3 3 2 2 2 2 2 2 2 2

{Avg}
* 223.33 161.00 165.33 140.50 145.50 142.50 143.00 142.00 161.00 167.00 179.50

{A T }

* 131.27 94.63 97.18 82.58 85.52 83.76 84.05 83.46 94.63 98.16 100.21

Chapter 12: Built in Functions (BiFs)

Data
Dec Year

{U}
240 133.81

{U}
320 191.54

{U}
0 229.83

Sum
560

###
2

{Avg}
280.00 2041.67

{A T }

164.57 1200.00

This describes the equations for the multiplicative model, they replace equations (7) to (10) in Multiplicative Model Equations above: (7) For each calendar period: {avg} = average of {U} over all actual periods. (8) For each calendar period: {AT} = 100 * {periodicity} * {avg} / (sum of all {avg}). (9) For each actual period: {ratio} = the value of {AT} corresponding to the period. (10) For each actual period {MA} = the average value of the seasonally adjusted data over all actual periods for the corresponding year. Equation (8) for the additive model is: {avg} - ((sum of all {avg}) / {periodicity}). For completeness {MA} and {ratio} are given sensible values to appear in the output. The value chosen for {MA} represents the constant level that the series would have to maintain for that year to give the observed total of original values in the actual periods. For a complete year of actuals it is the annual total divided by the periodicity. Unlike the average year method, the typical year method is robust when you exclude some of the periods within your history by removing them from the actuals. This is why it is used as the default when there are not enough actual periods to calculate the MA method. Compared to the average method it gives more weight to the seasonal factors in years with higher total annual value. There are further examples of this method in sample cube full2 slices 8 and 23.

Old messages
These occur if the timescale is unsuitable for making seasonal adjustment calculations. If either of them appear then no slice is calculated and all outputs of SeasonPro and SeasonLite will be zero. Message 564, Timescale has overlaps and/or gaps Message 565, Timescale has periods of unequal length

New Errors
Errors cause the result and output variables to be set to zero in the slice where the error occurs. Message 579, too much of year missing. @SeasonPro not enough actuals in slice Case 5 for 12 periods from Apr-00, outputs and result will be zero at season.lite[factors]. Not enough actuals to perform seasonal adjustment in some years. This message will appear if any year long sequence of periods between the first and last actual periods has more than 25% of the periods excluded as not actual. For a monthly time scale you must have at least 9 actual months in every 12 month sequence. This message appears in the sample cube lite.

User Guide 565

Chapter 12: Built in Functions (BiFs) Message 580, whole periods missing. @SeasonPro in slice Case 2 no actuals in periods Mar-01 Apr-01 May-01, outputs and result will be zero, at season.lite[factors]. Need at least one year of actuals to perform seasonal adjustment. This message will appear if there is a period that is not actual for all years between the first and last actual periods. The message shows the first appearance of each period, it appears in the sample cube lite.

New Warnings
A warning is issued when there is sufficient data to make the calculations, but the method you have chosen may not work well with so little data. Message 582, you are taking the average of one number. @SeasonPro in slice Case 21, some periods have only 1 actuals, 2 are preferred for method MA average, at season.full[seasonal factors]. Need enough data to calculate seasonal adjustment. For the MA average method you want at least two actuals to average for every period with in the year, you would prefer many more observations for each factor. When using the medial average method you need four actuals for each factor, so that you are averaging at least two numbers when you discard the highest and lowest values. The message appears in sample cube full. You will see a lot of this message if you apply the moving average method to data with less than three years actuals. Earlier versions of the BiF automatically and quietly substituted the typical year method in this case. We may want to drop this message altogether, or allow the model builder to take control by allowing a message severity level option in the methods. Message 583, not enough data to use the medial average. @SeasonPro in slice Case 24, some periods have only 1 actuals, 3 are needed for medial average, using MA average instead, at season.full[seasonal factors]. Need enough data to calculate seasonal adjustment. If you don't have three actuals for every period in the year then you can not use the medial average method. When you see this message the results for this slice will be based on the MA average method. This message appears in the sample cube full.

Sample new messages

Where to find examples of the messages (and examples of their absence) in the sample data:

Cube
Lite5

Case
3 4 5 6

Method
Medial Medial Medial Medial

Actuals
4yrs+4Ps 4yrs+3Ps 3yrs+4Ps 3yrs+3Ps

Message 1

Message 2

582 582 583 (to MA)

566 Analyst

Chapter 12: Built in Functions (BiFs)

Cube

Case
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 2 3 5

Method
Medial Medial Medial Medial MA MA MA MA Medial MA Average Typical Medial MA Average Typical Average Typical Average Medial Medial Medial

Actuals
2yrs+4Ps 2yrs+3Ps 1yr+4Ps 1yr+3Ps 2yrs+4Ps 2yrs+3Ps 1yr+4Ps 1yr+3Ps 0yrs+4Ps 0yrs+4Ps 0yrs+4Ps 0yrs+4Ps 1yr+0Ps 1yr+0Ps 1yr+0Ps 1yr+0Ps 2yrs+0Ps 2yrs+0Ps 1yr+4Ps No May, Jul, or Sep No Feb Big gap in 2000

Message 1
583 (to MA) 583 (to MA) 583 (to MA) 583 (to typical)

Message 2

582 582 582

582 582 583 (to typical) 580 580 580 580 583 (to typical) 583 (to typical) 582 582 582 582 582

582

579

User Guide 567

Chapter 12: Built in Functions (BiFs)

Cube

Case
3 4 5 6 7 8 12 21 24

Method
Medial Medial Medial Medial MA MA Medial MA Medial

Actuals
4yrs+0Qs 3yrs+3Qs 3yrs+0Qs 1yr+3Qs 3yrs+2Qs 2yrs+2Qs No Q4 2yrs+3Ms 2yrs+3Ms

Message 1
582 583 (to MA) 583 (to MA)

Message 2

582

582 580 582 583 (to MA) 582

4yrs+2Ps means four years plus two periods of actuals. 4yrs+2Qs means four years plus two quarters of actuals. 4yrs+2Ms means four years plus two months of actuals. Despite the large number of examples, there are still some gaps. Examples of uncentered moving averages and using linear regression to set the average are under-represented.

@Simul
The @Simul built in function provides the building blocks to simulate seasonal data using a variety of characteristics. It is used to test and explore how SeasonPro and other BiFs handle such data. This table shows the text you see in the BiF wizard when using @Simul.

Function
Param

Simul
Method

Simulations For Time Series

Params: 1=Period Number; 2=Repeat year 1; 3=Seasonal; 4=Normal; 5=Uniform.

Time Totals
Normal

Input

Input

Input, varies with the method (for example, first year Normal data for method 2) data entered across the periods of the timescale as described below. Simulations for time series Normal

Result

Output

568 Analyst

Chapter 12: Built in Functions (BiFs)

Methods Period Number Related Data

Method 1: Period Number. Adds the current period number to the Prime value entered in the first month of the timescale within the input line.

Initial Year Related Data

Method 2: Repeats the data in the input line for year 1 in all subsequent years. Method 8: Shows the repeated data as per method 2 Normalized as percentages.

Seasonal Data
Method 3: The Input line is used across the timescale to record: Period 1 - Degrees of freedom Period 2 - Amplitude first degree of freedom Period 3 onwards - Amplitude of each degree of freedom

Random Data.
Note: This data recalculates every time the cube recalculates. Method 4: Box Muller Standard Deviation. Calculates random data using Box Muller from a mean (input in Period 1) and standard deviation (input to period 2) of the Input line for the BiF. Method 5: Random Numbers for Specified Range. Calculates random whole numbers between the values specified in Periods 1 & 2 of the input line. Method 6: Histogram of Normal Distribution. Calculates random data from a histogram based upon a sample size (input in Period 1), mean (input in Period 2) and standard deviation (input to Period 3) of the Input line for the BiF. Method 7: Histogram of Uniform Distribution. Calculates random data from a histogram based upon a sample size (input in Period 1) and range of values (input in Periods 2 & 3) of the Input line for the BiF.

Examples
Period = @Simul(1; 1) Period = @Simul(1; {start-from}) Factors = @Simul(2; {first-year}) Factors = @Simul(3; {df-amplitude}) Random = @Simul(4; {mean-var}) Random = @Simul(5; {lower-upper}) {norm-hist} = @Simul(6; {number-mean-stddev})

User Guide 569

Chapter 12: Built in Functions (BiFs) {uniform-hist} = @Simul(7; {number-lower-upper}) factors = @Simul(8; {first-year})

Timescale
Any timescale may be used, the periodicity (number of periods in a year) is taken from the first period. When method = 3 the maximum value of {df} (degrees of freedom) is {periodicity}-1. When method = 8 the seasonal factors are normalized to add to 100 * {periodicity}.

Extra Information:
@Simul(1;1) is equivalent to @Feed(0;;1;0). @Simul(3;df) where {df}= 4, a, b, c, d in the first five periods of a monthly time scale gives seasonal factors with four degrees of freedom where, with t as the period number starting at 1, output = (a*Cos(30*t)) + (b*Sin(30*t)) + (c*Cos(60*t)) + (d*Sin(60*t)). More generally the amplitudes are applied to sine and cosine pairs of angles which are integer multiples of 360/{periodicity}. Thus the full monthly model with 11 degrees of freedom is: output = (a*Cos(30*t)) + (b*Sin(30*t)) + (c*Cos(60*t)) + (d*Sin(60*t)) + (e*Cos(90*t)) + (f*Sin(90*t)) + (g*Cos(120*t)) + (h*Sin(120*t)) + (i*Cos(150*t)) + (j*Sin(150*t)) + (k*Cos(180*t)) For a full quarterly model the full equation is: output = (a*Cos(90*t)) + (b*Sin(90*t)) + (c*Cos(180*t)) @Simul(4;mv) where (say) {mv} = 0 10 in the first two periods gives random normal variates with mean 0 and standard deviation 10 using the Box-Muller method. @Simul(5;ab) where (say) {ab} = 5 10 in the first two periods gives random uniform variates between 5 and 10 by choosing random integers between 1 and 10,001 and then mapping them onto the range [5,10]. @Simul(6; nmv} where (say) nmv = 2000 10 100 produces a histogram from a sample of 2000 numbers from the normal distribution with mean 10 and deviation 100, where the histogram cells are the periods with equal width covering the range of the sample. @Simul(7; nab) where (say) nab = 20000 6 12 produces a histogram from a sample of 20000 numbers taken from a uniform distribution with range [6, 12]. The cells are handled in the same way as for method 6. @Simul[8;{first-year}] if the input is all zero, the output is all 100.

Some of the methods have no need of any understanding of time. Where time is used, every timescale is treated as if were composed of periods of equal length. The @Simul BiF only uses the number of

570 Analyst

Chapter 12: Built in Functions (BiFs) periods and the periodicity (the number of periods that make up a whole year - calculated using the first period). In methods 4, 5, 6, and 7 random numbers are generated using the APL roll function and the random seed is set by during initialization from the accounting information. You could receive a different result each time you open the model and the result will change when it is recalculated. The basic APL pseudo-random process is appropriate for @Simul. Methods 6 and 7 give a visual indication of how close to the underlying distribution different sample sizes may get. You should use them with a pseudo time scale that has an suitable number of periods.

@StockFlow
Supply Outlook=@StockFlow(Prime; Opening Stock; Forecast Sales; Forecast Cover; Closing Stock; Actual Sales; Actual Cover; Actual Supply; Actual Closing; SwitchOver; Cover Units; Period Length; Max Supply; Min Supply; % Wastage; Wastage; Rounding Method; End Method; Outlook Method; Sales Outlook)

Input/ Output
Prime Input D-List Item

Description

Prime opening stock. The opening stock at the start of the first period. Opening Stock. Fed from the Closing Stock of the previous period. Forecast sales will be used in the period containing the switchover date and thereafter. Prior to the switchover date, forecast sales will be ignored. The forecast stock cover. How many days/periods of future sales the closing stock should support. For example, 100 means to set Closing Stock at such a level that it lasts 100 days based on depletion at the Sales Outlook rate. The default is for this to be measured in days, but this can be altered by defining a different time method. Closing Stock. Actual Closing Stock prior to the switchover date; the level required to meet the Forecast Stock Cover thereafter. Actual Sales input for historic periods only.

Opening Stock

Output

D-List Item

Forecast Sales

Input

D-List Item

Forecast Cover

Input

D-List Item

Closing Stock

Output

D-List Item

Actual Sales

Input

D-List Item

User Guide 571

Chapter 12: Built in Functions (BiFs)

Input/ Output
Actual Cover Output D-List Item

Description

Actual Stock Cover. How many days/periods of future sales the Closing Stock actually does support. Actual Supply input for historic periods only. Actual Closing Stock input for historic periods only. The period containing the switchover date is defined as the first future period.

Actual Supply Actual Closing

Input Input

D-List Item D-List Item

Switch Over

Input

None 19970501 Dlist Today 4 Cover Units Input

Treat all periods as historic = 1st May 1997 = use switchover date in timescale D-List = use todays date = use April in monthly timescale D-List Identifies the measure for Stock Cover in terms of future sales.

1 2 3

= Use calendar days. Default. = Use custom units from the item Period Length. = Use number of periods. Each detail item in the timescale D-List is a period. Available if you want to use non-standard calendar period lengths. For example: 4 - 4 - 5 for weeks in each period. Period Length will be ignored unless you set Cover Units=2.

Period Length

Input

D-List Item

Max Supply

Input

D-List Item or Limitation to the maximum supply available to Constant increase stock levels. If left blank, the default is for Max Supply to be allowed to go to infinity. 0 = no limit

572 Analyst

Chapter 12: Built in Functions (BiFs)

Input/ Output
1000

Description

= Maximum possible supply is 1000 in each time period.

Min Supply

Input

D-List Item or Limitation to the flow out of stock. If left blank, Constant the default is zero. For example: minimum supply cannot go negative. 0 = let stock deplete due to sales, but do not throw any away (the default). = the supply inflow can not be allowed to drop below 100. = obsolete stock cannot be disposed of at a rate of more than 500 units each periods. Percentage of opening stock that is wasted in each period. Changes in stock due to shrinkage (not explained by sales and supply). Wastage is = to % Wastage applied to the Opening Stock. = Do not round. This is the default if left blank.

100

-500

% Wastage

Input

D-List Item

Wastage

Output

D-List Item

Rounding Method

1 2

= Round each element. = Preserve the sum by changing the most obvious element(s). For example: the ones who rounded value is furthest from their original value. The method will take the first few it needs in the case of a tie. = Preserve the sum by rounding cumulated data and then taking the difference (the default).

User Guide 573

Chapter 12: Built in Functions (BiFs)

Input/ Output
End Method Input Integer Constant

Description

The number of periods over which to average sales when projecting beyond the last period in the timescale. This is used in the Closing Stock calculation toward the end of the timescale. The default is n=1, and n must not exceed the number of periods in the timescale D-List. = Use the average of the last 3 periods to project sales forward. How Forecast Sales input is used to provide future Sales Outlook.

Outlook Method Input

= Use Forecast Sales from the period containing the switchover date onwards, Actual Sales prior to this (the default method). = Restrict future sales if closing stock goes negative. Sales Outlook is equal to the Actual Sales history prior to the switchover date, Forecast Sales thereafter. See Outlook Method. The supply in future periods required to meet forecast stock cover based on forecast sales. The supply is subject to the constraints of Min and Max Supply. Prior to the switchover date, Supply Outlook equals Actual Supply.

Sales Outlook

Output

D-List Item

Supply Outlook BiF Result D-List Item

Troubleshooting
To insure that the BiF is displaying the correct results, click Help, Show Calculation Errors. If there are errors in the syntax, a message appears indicating where the formula has been incorrectly set up.

How StockFlow works

StockFlow works out the level of supply needed to meet target forecasts for stock cover. Supply Outlook = @StockFlow(Prime;{Opening Stock};{Forecast Sales};{Forecast Cover};{Closing Stock};{Actual Sales};{Actual Cover};{Actual Supply};{Actual Closing};19980301;1;{Period Length} ;{Max Supply};{Min Supply};{% Wastage}; Wastage;0;1;1;{Sales Outlook})

574 Analyst

Chapter 12: Built in Functions (BiFs) The supply is calculated to meet the Closing Stock target.

End Method
For the last few periods, the demand in the last period is replicated to provide any missing periods required by the level of stock cover. By default, the last period sales are replicated to provide for future periods. The period lengths are replicated in a similar manner. Alternatively, the End Method can be used to calculate an average demand over the last n periods and replicate this average over the future periods.

Outlook method
Outlook Method determines how Sales Outlook is calculated. Both Outlook methods try to set Sales Outlook to equal Actual Sales for historic periods and Forecast Sales for future periods. The difference is that the default Outlook Method (=1) allows for the Closing Stock to go negative in certain cases. This can be a desirable result if you are looking to identify stock shortfalls. However, if you do not want to allow the Closing Stock to go negative, you can restrict future sales by setting the Outlook Method parameter = 2.

Min and Max Supply

The maximum supply can be restricted due to factory capacity or the limits of subcontractors to supply goods. Simply enter a constant or a D-List item in the Max Supply parameter. If the Max Supply is left blank or entered as zero, this is assumed to mean no limit, that is, to let it go to infinity. So if you really want Max Supply to tend to zero you should just enter a very small number indeed. You may also restrict the minimum supply. The default for Min Supply is zero meaning that supply cannot be negative. In this case stock can only be depleted at the rate it is sold. However, you may enter a positive number that specifies a minimum supply level (for example, to fulfil contractual obligations). Alternatively, you can enter a negative number for minimum supply. A negative minimum supply may be thought of as being the maximum rate at which stock may be returned to the supplier or disposed of by some means other than selling it. Consider the scenario when you have an actual stock cover of over 80 days one month and a planned cover of 30 days the next month. Even with zero supply, you can not rely on sufficient sales in one month to achieve such a dramatic reduction in stock levels. Instead, you have to dispose of or give away stock (negative supply) in order to bring the stock levels down so quickly. The closing stock levels and actual stock cover are adjusted accordingly.

Wastage
Optionally, you may enter a % Wastage for each period to allow for part of the stock being lost. A % Wastage of 2 in a period means 2% of the opening stock is expected to be wastage.

Cover Units and Period Length

The default is to use calendar days for Cover Units (=1). This means that Forecast Cover is measured in stock-turn days; that is, the number of days it takes to deplete stocks based on the Sales Outlook.

User Guide 575

Chapter 12: Built in Functions (BiFs) Alternatively you can use custom units entered in the item Period Length. For example, you can enter 4, 4, and 5 in the Period Length row to denote that the first and second periods are 4 weeks long and the third 5 weeks long. Forecast Cover would then be entered in weeks rather than days. You must set Cover Units=2 or it will ignore the Period Length item. The final alternative is to set Cover Units=3. In this case, Forecast Cover should be input in periods. Each detail item in the timescale D-List is defined as a single period.

Rounding Method
The default Rounding Method (=0) means do not round. This is the recommended method. The other methods round to integers. The rounding method can be used to round each element (1) or to round each time total (2 and 3) . Using methods 2 and 3, the elements are rounded in such a way that they continue to add up to the time total. 0 means do not round 1 means round each element 2 means preserve the sum by changing the most obvious elements (that is, the ones whose rounded value is furthest from their original value). This method will take the first few it needs in the case of a tie. 3 means preserve the sum by rounding cumulated data and then taking the difference.

Pd01
Original Method 0 Method 1 Method 2 Method 3 1.5 1.5 2 2 2

Pd02
1.5 1.5 2 2 1

Pd03
1.5 1.5 2 1 2

Pd04
1.5 1.5 2 1 1

Total
6.0 6.0 8 6 6

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display the Supply Outlook. 4. Click Change item attributes. 5. Click BiF. 6. Select Stockflow from the Function Name list.

576 Analyst

Chapter 12: Built in Functions (BiFs) 7. Click Next. 8. Double-click the parameters in the BiF Function Wizard. 9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@StockFlowAF
Supply Outlook=@StockFlowAf(Prime; Opening Stock; Forecast Sales; Forecast Cover; Closing Stock; Actual Sales; Actual Cover; Actual Supply; Actual Closing; Forecast flag; Cover Units; Period Length; Max Supply; Min Supply; % Wastage; Wastage; Rounding Method; End Method; Outlook Method; Sales Outlook)

Input/ Output
Prime Input D-List Item

Description

Prime opening stock. The opening stock at the start of the first period. Opening Stock. Fed from the Closing Stock of the previous period. Forecast sales will be used in the first period for which forecast flag has a value greater than 1 and thereafter. The forecast stock cover. How many days/periods of future sales the closing stock should support. For example, 100 means to set Closing Stock at such a level that it lasts 100 days based on depletion at the Sales Outlook rate. The default is for this to be measured in days, but this can be altered by defining a different time method. Closing Stock. Actual Closing Stock prior to the switchover date; the level required to meet the Forecast Stock Cover thereafter. Actual Sales input for historic periods only. Actual Stock Cover. How many days/periods of future sales the Closing Stock actually does support.

Opening Stock Output

D-List Item

Forecast Sales Input

D-List Item

Forecast Cover Input

D-List Item

Closing Stock Output

D-List Item

Actual Sales Actual Cover

Input Output

D-List Item D-List Item

User Guide 577

Chapter 12: Built in Functions (BiFs)

Input/ Output
Actual Supply Input Actual Closing Input Forecast Flag Input D-List Item D-List Item

Description

Actual Supply input for historic periods only. Actual Closing Stock input for historic periods only. Enter a flag to act as a different switchover date on each page. The first value > 1 indicates the start of forecast periods. This item can be formatted on a D-list with the two items Actual (IID1) and Forecast (IID2). Identifies the measure for Stock Cover in terms of future sales.

Cover Units

Input

1 2 3

= Use calendar days. Default. = Use custom units from the item Period Length. = Use number of periods. Each detail item in the timescale D-List is a period. Available if you want to use non-standard calendar period lengths. For example: 4 - 4 - 5 for weeks in each period. Period Length will be ignored unless you set Cover Units=2. Limitation to the maximum supply available to increase stock levels. If left blank, the default is for Max Supply to be allowed to go to infinity. = no limit = Maximum possible supply is 1000 in each time period. Limitation to the flow out of stock. If left blank, the default is zero. For example: minimum supply cannot go negative. = let stock deplete due to sales, but do not throw any away (the default).

Period Length Input

D-List Item

Max Supply

Input

D-List Item or Constant

0 1000

Min Supply

Input

D-List Item or Constant

578 Analyst

Chapter 12: Built in Functions (BiFs)

Input/ Output
100

Description

= the supply inflow can not be allowed to drop below 100. = obsolete stock cannot be disposed of at a rate of more than 500 units each periods. Percentage of opening stock that is wasted in each period. Changes in stock due to shrinkage (not explained by sales and supply). Wastage is = to % Wastage applied to the Opening Stock. = Do not round. This is the default if left blank.

-500

% Wastage

Input

D-List Item

Wastage

Output

D-List Item

Rounding Method

1 2

= Round each element. = Preserve the sum by changing the most obvious element(s). For example: the ones who rounded value is furthest from their original value. The method will take the first few it needs in the case of a tie. = Preserve the sum by rounding cumulated data and then taking the difference (the default). The number of periods over which to average sales when projecting beyond the last period in the timescale. This is used in the Closing Stock calculation toward the end of the timescale. The default is n=1, and n must not exceed the number of periods in the timescale D-List. = Use the average of the last 3 periods to project sales forward. How Forecast Sales input is used to provide future Sales Outlook.

End Method

Input

Integer Constant

Outlook Method

Input

= Use Forecast Sales from the period containing the A/F flag onwards, Actual Sales prior to this (the default method).

User Guide 579

Chapter 12: Built in Functions (BiFs)

Input/ Output
2 Sales Outlook Output D-List Item

Description

= Restrict future sales if closing stock goes negative. Sales Outlook is equal to the Actual Sales history prior to the A/F flag, Forecast Sales thereafter. See Outlook Method. The supply in future periods required to meet forecast stock cover based on forecast sales. The supply is subject to the constraints of Min and Max Supply. Prior to the A/F flag, Supply Outlook equals Actual Supply.

Supply Outlook

BiF Result D-List Item

How StockFlowAF works

@StockFlowAF is based on the standard @StockFlow BiF, which allows you to input stock cover and work out what purchases were needed to meet the target stock levels. In @StockFlow, the switchover date applies to the entire D-Cube, but in @StockFlowAF, you can enter a flag (Actual or Forecast) to act as a different switchover date on each page. This allows you to work out the stockflow for different scenarios where the switchover date may vary. To define the switchover date, create a D-List with the two items Actual and Forecast (in that order) . Format the item Forecast Flag on this D-List. You can then enter the word, "Actual," for historic periods and "Forecast" for future periods. The BiF uses specific IID numbers of each D-List item to define the switchover date (Actual=1 and Forecast=2). To find an IID number, click the Summary Info button in the Analyst toolbar.

Troubleshooting
To ensure that the BiF is displaying the correct results, click Help, Show Calculation Errors. If there are errors in the syntax, a message appears indicating where the formula has been incorrectly set up.

End Method
For the last few periods, the demand in the last period is replicated to provide any missing periods required by the level of stock cover. By default, the last period sales are replicated to provide for future periods. The period lengths are replicated in a similar manner. Alternatively, the End Method can be used to calculate an average demand over the last n periods and replicate this average over the future periods.

Outlook method
Outlook Method determines how Sales Outlook is calculated.

580 Analyst

Chapter 12: Built in Functions (BiFs) Both Outlook methods try to set Sales Outlook to equal Actual Sales for historic periods and Forecast Sales for future periods. The difference is that the default Outlook Method (=1) allows for the Closing Stock to go negative in certain cases. This can be a desirable result if you are looking to identify stock shortfalls. However, if you do not want to allow the Closing Stock to go negative, you can restrict future sales by setting the Outlook Method. parameter = 2.

Min and Max Supply

The maximum supply can be restricted due to factory capacity or the limits of subcontractors to supply goods. Simply enter a constant or a D-List item in the Max Supply parameter. If the Max Supply is left blank or entered as zero, this is assumed to mean no limit, that is, to let it go to infinity. So if you really want Max Supply to tend to zero you should just enter a very small number indeed. You may also restrict the minimum supply. The default for Min Supply is zero meaning that supply cannot be negative. In this case stock can only be depleted at the rate it is sold. However, you may enter a positive number that specifies a minimum supply level (for example, to fulfil contractual obligations). Alternatively, you can enter a negative number for minimum supply. A negative minimum supply may be thought of as being the maximum rate at which stock may be returned to the supplier or disposed of by some means other than selling it. Consider the scenario when you have an actual stock cover of over 80 days one month and a planned cover of 30 days the next month. Even with zero supply, you can not rely on sufficient sales in one month to achieve such a dramatic reduction in stock levels. Instead, you have to dispose of or give away stock (negative supply) in order to bring the stock levels down so quickly. The closing stock levels and actual stock cover are adjusted accordingly.

Wastage
Optionally, you may enter a % Wastage for each period to allow for part of the stock being lost. A % Wastage of 2 in a period means 2% of the opening stock is expected to be wastage.

Cover Units and Period Length

The default is to use calendar days for Cover Units (=1). This means that Forecast Cover is measured in stock-turn days; that is, the number of days it takes to deplete stocks based on the Sales Outlook. Alternatively you can use custom units entered in the item Period Length. For example, you can enter 4, 4, and 5 in the Period Length row to denote that the first and second periods are 4 weeks long and the third 5 weeks long. Forecast Cover would then be entered in weeks rather than days. You must set Cover Units=2 or it will ignore the Period Length item. The final alternative is to set Cover Units=3. In this case, Forecast Cover should be input in periods. Each detail item in the timescale D-List is defined as a single period.

Rounding Method
The default Rounding Method (= 0) means do not round. This is the recommended method. The other methods round to integers.

User Guide 581

Chapter 12: Built in Functions (BiFs) The rounding method can be used to round each element (1) or to round each time total (2 and 3) . Using methods 2 and 3, the elements are rounded in such a way that they continue to add up to the time total. 0 means do not round 1 means round each element 2 means preserve the sum by changing the most obvious elements (that is, the ones whose rounded value is furthest from their original value). This method will take the first few it needs in the case of a tie. 3 means preserve the sum by rounding cumulated data and then taking the difference.

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation (p. 93) D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to display the Supply Outlook. 4. Click Change item attributes. 5. Click BiF. 6. Select StockflowAF from the Function Name list. 7. Click Next. 8. Double-click the parameters in the BiF Function Wizard. 9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@StockflowBQ
The @StockflowBQ built in function lets you use batch quantities in Stockflow calculations. Supply Outlook=@StockFlowAf(Prime; Opening Stock; Forecast Sales; Forecast Cover; Closing Stock; Actual Sales; Actual Cover; Actual Supply; Actual Closing; Forecast flag; Cover Units; Period Length; Max Supply; Min Supply; Batch Quantity; Minimum Method; % Wastage; Wastage; Rounding Method; End Method; Outlook Method; Sales Outlook)

Function
Input

StockFlowBQ
Prime

Stock Flow with Batch Quantity

Opening stock at the beginning of the first period

Time Totals
Normal

582 Analyst

Chapter 12: Built in Functions (BiFs)

Function
Output

StockFlowBQ
Opening Stock

Stock Flow with Batch Quantity

Opening stock, output for both actual and future periods

Time Totals
Average

Input

Forecast Sales

The forecast of record for actual and future Normal periods How many days/periods (per Cover Units) of First future sales closing stock should support Closing stock, output for both actual and forecast periods Normal

Input

Forecast Cover

Output

Closing Stock

Input Output

Actual Sales Actual Cover

Actual sales history, input for actual periods Normal How many days/periods (per Cover Units) of Last future sales closing stock does support Actual Supply, input for actual periods First

Input Input Input

Actual Supply Actual Closing Forecast flag

Actual Closing Stock, input for actual periods Normal The first value > 1 indicates the start of forecast periods 1 = Calendar days in the time scale, 2 = use Custom Units, 3 = number of periods Average

Param

Cover Units

Normal

Input

Period Length

Custom Cover Units, for example the number Average of weeks in each month Upper limit on the supply in each period. Zero (the default) means no limit. Lower limit on the supply in each period. Default is zero. In forecast periods Supply Outlook will be an integer multiple of this quantity. Normal

Input

Max Supply

Input

Min Supply

Normal

Input

Batch Quantity

Average

Input Input

Minimum Method Modifies the effect of Min Supply % Wastage

Average

% of forecast opening stock lost in a future Average period

User Guide 583

Chapter 12: Built in Functions (BiFs)

Function
Output

StockFlowBQ
Wastage

Stock Flow with Batch Quantity

Actual is unexplained change in stock, forecast is %Wastage applied to Opening Stock

Time Totals
Normal

Param

Rounding Method All outputs may be rounded to integers. Default is no rounding. 0=Do not round 1=Round each element 2=means preserve the sum by changing the most obvious elements (that is, the ones whose rounded value is furthest from their original value). This method will take the first few it needs in the case of a tie. 3=means preserve the sum by rounding cumulated data and then taking the difference.

Normal

Param

End Method

How to project forecast sales past the last Normal period in the timescale. Enter the number of periods over which to average sales when calculating the projected forward sales. Normal

Param

Outlook Method How to calculate sales outlook for future periods. Sales Outlook

Output

Sales history for actual periods, future period Normal calculations depend on Outlook Method Actual Supply and calculated supply outlook Normal

Result

Supply Outlook

Methods
See "@StockFlow" (p. 571) for complete information on Methods.

Batch Quantity.
When {Batch Quantity} is non-zero, the {Supply Outlook} will be rounded up to the next integer multiple of {Batch Quantity}. Zero {Batch Quantity} has no effect, non-integer values are permitted, and any sign is ignored. StockFlowAF has more information about other inputs and calculations.

584 Analyst

Chapter 12: Built in Functions (BiFs)

Minimum Method
Applies to {Supply Outlook} in forecast periods. It modifies the effect of {Min Supply}. When method = 0 {Min Supply} is strictly enforced. When method = 1 Supply Outlook may be zero in forecast periods, even if {Min Supply} is non-zero.

Minimum, Maximum and batch size

StockFlowBQ resolves inconsistent inputs in the following manner: If {Min Supply} is positive and {Batch Size} is positive, then round {Min Supply} up to the next integer multiple of {Batch Size}. If {Batch Size} is positive and {Max Supply} is positive, then round {Max Supply} down to the next integer multiple of {Batch Size}. If {Min Supply} > {Max Supply}, then set {Max Supply} = {Min Supply}.

@Tier
@Tier calculates a different percentage for each tier. Tiers are entered as a percentage and a bandwidth. Up to 20 tiers are allowed. Each bandwidth should be entered as a positive number, with the first tier always starting at zero. You do not need to enter all tiers. The percentage after the last non-zero bandwidth applies to any residue. Tier result = @Tier(Value, Tier1%, Tier1, Tier2%, Tier2,Tier3% ..... Tier 20%)

Input/Output Parameter
Value Tier 1 % Input Input D-List Item D-List Item or Constant D-List Item or Constant D-List Item or Constant D-List Item or Constant D-List Item

Description
Input amount The percentage to be applied between zero and Tier The bandwidth of Tier 1, starting at zero

Tier 1

Input

Tier 2 %

Input

The percentage to be applied in Tier 2

Tier 2

Input

The bandwidth of Tier 2, starting at the top of Tier 2 The calculated tier result

Tier Result

Result

Tier result = Tier 1 % applied over the bandwidth of tier 1 + Tier 2 % applied over the bandwidth of tier 2 User Guide 585

Chapter 12: Built in Functions (BiFs) + Tier 3 % applied over the bandwidth of tier 3 + Tier 20% applied from tier 20 and above.and so on.

Example
A tax bill is the classic example of a tiered calculation. If you are taxed, based on 0 to 3000 at 0%, 3000 to 30000 at 20%, above 30000 at 40%, then the tax bands are entered as bandwidths of 3000 and 27000 (rather than the break-points of 3000 and 30000).

Jan
Value % 1st Tier Bandwidth 1st Tier % 2nd Tier Bandwidth 2nd Tier % 3rd Tier and above Tier Result So for the 35000 pay, 2000 0 3000 20 27000 40 0

Feb
15000 0 3000 20 27000 40 2400

Mar
25000 0 3000 20 27000 40 4400

Apr
35000 0 3000 20 27000 40 7400

Tier Result = (First 3000 at 0%)+ (Next 27000 at 20%) + (Final 5000 at 40%) = 0 + 5400 + 2000 = 7400 Note: You do not need to enter all tiers. The percentage after the last non-zero bandwidth apples to any residue.

@Time
Time Result = @Time (Input)

Input/Output Parameter Description

Input Input D-List Item The option you require for time information. 1 = Now (Current system date and time). 2 = When the cube was last saved.

586 Analyst

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter Description

3 = Start - the date and time at the start of this period. 4 = Middle - the date and time at the middle of this period. 5 = End - the date and time at the end of this period. 6 = Days - the number of days in this period. 7 = IIDs - the IIDs of the defined detail periods in the timescale. 8 = Current: Sets a flag = 1 in the period containing system date. 9 = Switchover: Sets a flag =1 in the period containing switchover date. 10 = Actual: Sets a flag =1 in periods up to, but not including, the period containing the system date (current) . 11 = Cycle: The number of periods like this in a year to the nearest whole number (minimum 1). 12 = Period: Numbers the periods within a year, starting again at 1 each year and counting up until it reaches the total number of periods in the year (as defined in cycle) . 13 = First: Sets a flag =1 in the first period of every timescale subtotal. 14 = Last: Sets a flag =1 in the last period of every timescale subtotal. 15 = Actual_swo: Sets a flag =1 in periods up to, but not including, the period containing the switchover date. 16 = LastMinute: Returns the date and time 1 minute before midnight on last day of period. 17 = Method - Returns the middle of each period in year units, where 2003.5 means the middle of 2003. It is used by Cycles as its measure of time. User Guide 587

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter Description

Time Output Result D-List Item Returns time-related information. For options 1 to 5, and 16, this should be date formatted, otherwise choose a number format. If a flag is set, it returns a 1. If no flag is set, it returns a zero. D-List Item Time information depending on the option chosen.

Result Result

How @Time Works

@Time returns the information requested by the option you have input. For a standard timescale, the start of a period is at midnight on the first day. The middle of a period may be at noon or midnight depending how many days there are in the period. The end of a period is midnight on the last day which is formatted as midnight at the start of the next day.

Generic Timescales
Start is 1 for 1st period, 2 for 2nd period and so on. Middle is 1.5 for 1st period, 2.5 for 2nd period and so on. End is 2 for 1st period, 3 for 2nd period and so on.

Generic Timescales have no date associated with each period and all the periods are the same length

Daily Timescales
Generic daily timescales have a cycle of 7 (days in a week). Each day is assumed to have length 1/ 365 of a year, the first day starts at 1.0. So the middle points of the first few days are 1.0014, 1. 0041, 1.0068, 1.0096. The middle of each day is 1/365 of year higher than the middle of the previous day.

Non-Daily Timescales
For non-daily timescales, the {cycle} (time method 11) is the number of periods in the year. The {period number} is the position of the period within the year (time method 12). The year number starts at zero and is increased by one at each period where the {period number} is one. The {year units value for the middle of each period} = {year number} + ({period number} - 0.5) / {cycle}. For a monthly time scale starting with January the first few values are 1.0417, 1.1250, 1.2083, 1. 2917. For a monthly time scale starting with December the first few values are 0.9583, 1.0417, 1.1250, 1.2083.

588 Analyst

Chapter 12: Built in Functions (BiFs)

Standard timescales
Although it is usual to expect each period in a time scale to have roughly the same length when using the BiF Cycles and Time method 17, each period is evaluated independently and the calculations work just the same when period length varies between periods.

A Whole Number of Periods Make Up a Year

All months are treated as the same length within the year. This means that the middle of January is at the same point in the year regardless of whether it is a leap year or not. Also the time between (say) the middle of January and the middle of February will be the same as that between the middle of March and the middle of April. This calculation applies where all periods have cycle = 1, 2, 3, 4, 6, or 12, where cycle is time method 11. In addition each period must start with the first day of the month in which such a period usually starts for the calculation to apply to this period. Where cycle =1 the length of the period must be less than 367 days. For these periods the calculation is: middle = year + (period number - 0.5) / cycle

Other Periods
This means periods that individually or collectively do not satisfy the conditions above. The calculation steps are: Find the day number of the middle of the period (equivalent to time method 4) Deduce the {year} in which that day number falls Find how many {days into the year} the middle is Find the {length} in days of the year (365 or 366) {middle in year units} = {year} + {days into the year} / {length}

Example 1 - Date and No of Days Options

Consider a timescale for the Financial Year 2004 with sub-totals for each half, H1 and H2. Assuming the current date is 27 March 2004 then the Bif would return the following values:

Jan
1 - Now 2 - Last Saved 3 - Start 4 - Middle 5 - End 27/03/04 27/03/04 01/01/04 16/01/04 01/02/04

Feb
27/03/04 27/03/04 01/02/04 15/02/04 01/03/04

Mar
27/03/04 27/03/04 01/03/04 16/03/04 01/04/04

Apr
27/03/04 27/03/04 01/04/04 16/04/04 01/05/04

May
27/03/04 27/03/04 01/05/04 16/05/04 01/06/04

Jun
27/03/04 27/03/04 01/06/04 16/06/04 01/07/04

H1
27/03/04 27/03/04 01/01/04 01/04/04 01/07/04

User Guide 589

Chapter 12: Built in Functions (BiFs)

Jan
6 - Days 16 - Last Minute 31 31/01/04

Feb
29 29/02/04

Mar
31 31/03/04

Apr
30 30/04/04

May
31 31/05/04

Jun
30 30/06/04

H1
182 30/06/04

Jul
1 - Now 2 - Last Saved 3 - Start 27/03/04 27/03/04

Aug
27/03/04 27/03/04

Sep
27/03/04 27/03/04

Oct
27/03/04 27/03/04

Nov
27/03/04 27/03/04

Dec
27/03/04 27/03/04

H2
27/03/04 27/03/04

FY
27/03/04 27/03/04

01/07/04

01/08/04 16/08/04 01/09/04 31 31/08/04

01/09/04 16/09/04 01/10/04 30 30/09/04

01/10/04 16/10/04 01/11/04 31 31/10/04

01/11/04 16/11/04 01/12/04 30 30/11/04

01/12/04 16/12/04 01/01/05 31 31/12/04

01/07/04 01/10/04 01/01/05 184 31/12/04

01/01/04 01/07/04 01/01/05 366 31/12/04

4 - Middle 16/07/04 5 - End 6 - Days 16 - Last Minute 01/08/04 31 31/07/04

Start Middle and End Dates

The middle of a period consisting of an odd number of days, for example August, is returned as mid-day on the middle day. Where a period consists of an even number of days, for example November, the middle of the time period is at midnight. The end of each period is at midnight on the last day, but this is returned as time 00.00 with the date of the following day. For example the end of August is midnight on the night of 31st August and 1st September, but the result returned is 01.09.00 -00.00 and therefore 01/09/04 when formatted as DD/MM/YY. The last minute of each period returns 23:59 with the date of the last day of the period. For example the last minute of August is 23.59 on the night of 30th August so the result formatted as DD/MM/ YY is 31/08/04.

Example 2 - Other Options

Using the same timescale for the Financial Year 2004 with sub-totals for each half, H1 and H2. Assuming the current date is 27 March 2004 and a switchover date set in the D-List as 01/06/04 then the Bif would return the following values:

590 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
7-IID's 8-Current 9-Switchover 10-Actual 11-Cycle 12-Period 13-First 14-Last 15-Actual Switchover 17-Method 1 0 0 1 12 1 1 0 1

Feb
2 0 0 1 12 2 0 0 1

Mar
3 1 0 0 12 3 0 0 1

Apr
4 0 0 0 12 4 0 0 1

May
5 0 0 0 12 5 0 0 1

Jun
6 0 1 0 12 6 0 1 0

H1

1 1 2 12

1 1 5

2004.04 2004.13 2004.21 2004.29 2004.38 2004.46 Jul Aug 8 0 0 0 12 8 0 0 0 Sep 9 0 0 0 12 9 0 0 0 Oct 10 0 0 0 12 10 0 0 0 Nov 11 0 0 0 12 11 0 0 0 Dec 12 0 0 0 12 12 0 1 0 1 1 0 1 1 5 0 0 0 12 1 1 2 12 H2 FY

7-IID's 8-Current 9-Switchover 10-Actual 11-Cycle 12-Period 13-First 14-Last 15-Actual Switchover 17-Method

7 0 0 0 12 7 1 0 0

2004.54 2004.63 2004.71 2004.79 2004.88 2004.96

User Guide 591

Chapter 12: Built in Functions (BiFs) Option 17 Method is relevant if you want to apply D-Lists with your own equations using time to any standard timescale. It is designed to satisfy these requirements for equations (like cycles) which are functions of time to be calculated at the middle of each timescale period: All periods with the same periodicity (number of periods in a year) should be considered the same length All years should be considered the same length, whether leap years or not. The equations should work well in time scales with periods of varying lengths.

Because this method is designed to support seasonal adjustment, it concentrates on months; {two months}; quarters;{four months}; {six months}; and {whole years} all of which must start on the first day of the appropriate calendar month. The typical planning timescale where it is needed might start with 24 months, continue with 4 quarters, then 3 years. Where SeasonPro and SeasonLite fit lines through data they treat each period as the same length. Thus in a standard monthly timescale each month is treated as a twelfth of a year and the middle of each month is in the same relative position within the year for all years, whether or not they are leap years. SeasonPro includes the concept of Working Days if you wish to build number of days in a period into your seasonal adjustments. Generic timescales have no date associated with each period and all the periods are the same length.

Steps to Use this BiF

1. Set up a D-Cube with a timescale D-List and a calculation D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to calculate the Time result. 4. Click Change item attributes. 5. Click BiF. 6. Select Time from the Function Name list. 7. Click Next. 8. Double-click the Input parameter that contains the inputs, or enter a number from 1 to 7 depending on the option required. 9. Click Finish. Note: It is advisable to set the Format column for the Result item. For options 1 to 5, a suitable date/time format should be selected. For option 6, a numeric format is appropriate. For Option 7, the item should be formatted on the timescale D-List itself. 10. Click Apply. 11. Save the D-List.

592 Analyst

Chapter 12: Built in Functions (BiFs)

@TimeSum
TimeSum=@TimeSum (Amount, Periods, Arrears/Advance, End, Override, Days in Period, Indicator) Input/Output Parameter
Amount Periods Input Input D-List Item D-List Item

Description
The expense amount to accrue. The number of periods to add up to determine the size of the bill. For example, if you enter 3, the BiF accumulates three periods. This parameter reads the Advance/ Arrears parameter to determine whether to count the periods forward (Advance) or backward (Arrears). The current period is always included. Periods are processed in chronological order, regardless of the sequence of the periods in the timescale D-List. No check is made to ensure that periods are contiguous and not overlapping.

Arrears/ Advance

Input

D-List Item or Blank = In arrears Constant 1 = In arrears 2 = In advance

End

Input

D-List Item or How to fill in missing data. Missing periods are Constant treated as zero. 0 = Zero (default) 1 = Average 2 = Replicate 3 = Override-The override is used even if the number of periods is 0. 4 =Spare

Override

Input

D-List Item

Only used when the End parameter is set to 3 (Override). Length of period in days. Only used when the Indicator parameter is set to 1 (Use Days in Period).

Days in Period

Input

D-List Item

User Guide 593

Chapter 12: Built in Functions (BiFs)

Input/Output Parameter
Indicator Input

Description

D-List Item or 0 = Number of periods (default) Constant 1 = Use Days in Period-If you set the Indicator to 1, Days in Period to 0 or a negative value and number of Periods is not 0, the result for this period will be 0. If the length of the Periods is 0, the length of the sum of many relocation of it is also 0. 2 = Use days from the timescale D-List.

TimeSum BiF result

D-List Item

The cash payments.

The @TimeSum BiF allows you to accumulate an expense in your P&L over a specified number of periods in advance or arrears. For example, you might want your electricity bill to be paid quarterly in arrears starting in March, or an insurance bill to be paid 12 periods in advance with a single annual payment in January. You can use @TimeSum in conjunction with @Delay to convert an expense stream in the P&L first into invoice amounts, then into cash payments.

How @TimeSum works

The examples in this section accumulate the Expense amount and display the @TimeSum BiF result in the Invoice Amount row. The D-List IIDs have been set up to match the indicators for the end conditions and the advance/arrears flag, but you also could use a number. The following example shows Pay quarterly in arrears, first invoice in March.

Jan
Expense No of Periods to Accumulate In Advance / In Arrears Invoice Amount 0 10 0

Feb
20 0

Mar
30 3 Arrears

Apr
10 0

May
10 0

Jun
20 3 Arrears

60

40

The following example shows Pay quarterly in arrears, first invoice in February. Because December last year is missing, you could average January and February to get an estimate.

Jan
Expense 10

Feb
20

Mar
30

Apr
10

May
10

Jun
20

594 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
No of Periods to Accumulate In Advance / In Arrears End Conditions Invoice Amount 0 0

Feb
3 Arrears Average 45

Mar
0

Apr
0

May
3 Arrears

Jun
0

50

The following example shows Quarterly in arrears, starting in February, but no end conditions, so Decembers expense is ignored.

Jan
Expense No of Periods to Accumulate In Advance / In Arrears End Conditions Invoice Amount 0 10 0

Feb
20 3 Arrears

Mar
30 0

Apr
10 0

May
10 3 Arrears

Jun
20 0

30

50

The following example shows Quarterly in advance, starting in January.

Jan
Expense 10

Feb
20 0

Mar
30 0

Apr
10 3 Advance

May
10 0

Jun
20 0

No of Periods to Accumulate 3 In Advance / In Arrears End Conditions Invoice Amount 60 Advance

40

The following example shows 12 months in advance, starting in March. The end conditions are to replicate Junes figures to estimate the missing periods. In this case, June is the last chronological period of the timescale D-List. The invoice amount is calculated by adding up March to February next year. July through February next year are all assumed to be the same as Junes expense.

User Guide 595

Chapter 12: Built in Functions (BiFs)

Jan
Expense No of Periods to Accumulate In Advance / In Arrears End Conditions Invoice Amount 0 10 0

Feb
20 0

Mar
30 12

Apr
10 0

May
10 0

Jun
20 0

Advance Replicate 0 230 0 0 0

The following example shows Quarterly in arrears, starting in March, but overriding the result when told to. In this case, the calculation for March is ignored, and the override figure is used even though there is enough data to calculate Marchs invoice.

Jan
Expense 10

Feb
20 0

Mar
30 3 Arrears Override 99

Apr
10 0

May
10 0

Jun
20 3 Arrears

No of Periods to Accumulate 0 In Advance / In Arrears End Conditions Manual Override Invoice Amount 0

99

40

The following example shows one period in arrears. In fact, one period in advance would give you the same result, as you always include the current period. The timing of the invoice payment is another matter.

Jan
Expense 10

Feb
20 1 Arrears

Mar
30 1 Arrears

Apr
10 1 Arrears

May
10 1 Arrears

Jun
20 1 Arrears

No of Periods to Accumulate 1 In Advance / In Arrears End Conditions Arrears

596 Analyst

Chapter 12: Built in Functions (BiFs)

Jan
Manual Override Invoice Amount 10

Feb

Mar

Apr

May

Jun

20

30

10

10

20

The following example shows how the TimeSum and Delay BiF can be combined to calculate the cashflow effect. @TimeSum calculates the invoice amounts whereas @Delay sets the timing for the invoice payments. In this example an Invoice is raised quarterly in arrears and payment occurs 2 months later.

Jan
Expense 10

Feb
20 0

Mar
30 3 Arrears

Apr
10 0

May
10 0

Jun
20 3 Arrears

No of Periods to Accumulate 0 In Advance / In Arrears Invoice Amount % This Period % Next Period % Pd +2 % Pd +3 % Pd +4 Payment 0 0 0 0 0 0 0

0 0 0 0 0 0 0

60 0 0 100 0 0 0

0 0 0 0 0 0 0

0 0 0 0 0 0 60

40 0 0 100 0 0 0

The following example shows Invoice monthly in arrears with a mixed timescale moving from months to years, and payment occurring next month. So 1/12 = 8.3% of year 2's invoices get paid in year 3, the remaining 91.7% get paid within year 2. Year 1 is a Total in the timescale while Years 2 and 3 are detail items.

Oct Y1
Expense No of Periods to Accumulate 30 1

Nov Y1 Dec Y1 Year 1

40 1 40 1 300 12

Year 2
400 1

Year 3
500 1

User Guide 597

Chapter 12: Built in Functions (BiFs)

Oct Y1
In Advance / In Arrears Invoice Amount % This Period % Next Period % Pd +2 % Pd +3 % Pd +4 Payment Arrears 30 0 100 0 0 0 40

Nov Y1 Dec Y1 Year 1

Arrears 40 0 100 0 0 0 30 Arrears 40 0 100 0 0 0 40 300 0 1200 0 0 0 260

Year 2
Arrears 400 92 8 0 0 0 407

Year 3
Arrears 500 92 8 0 0 0 492

The Payment in Year 2 therefore comprises the Invoice amount of 40 from December plus 91.7% of the Year 2 total of 400, for example: 40+91.7%x400 = 40+366.8 = 407. The following example shows Quarterly in advance for uneven period lengths.

Oct Y1
Expense No of Periods to Accumulate In Advance / In Arrears Days In Period Invoice Amount 30 0 30 0

Nov Y1 Dec Y1 Year 1

40 3 40 0 300 12

Year 2
400

Year 3
500

Advance 30 113 30 0 360 323 360 360

In this example, the indicator has been set to 1 so that it uses the Days in Period row. Therefore, 3 periods in advance is interpreted as 90 days. The Invoice is calculated by looking forward 90 days from November 1. Invoice, Nov = Nov charge + Dec charge + (30 / 360) * Yr2 charge = 40 + 40 + (30/360) * 400 = 113.33 The following example shows 24 months in advance, starting in October. In this example, the periods are of uneven length and periods are missing.

598 Analyst

Chapter 12: Built in Functions (BiFs)

Oct Y1
Expense No of Periods to Accumulate 30 24

Nov Y1 Dec Y1 Year 1 Year 2

40 0 40 0 300 12 400

In Advance / In Arrears Advance Days In Period Invoice Amount 30 30 30 816 360 0 360 0 816 0

If the Indicator is set to 1, 24 is interpreted as (24 * 30) = 720 days because there are 30 days in the Days in Period, October cell. If the end conditions are set to average, an average daily charge is used for the missing 270 days for which there is no data. Invoice, Oct = (Charge, Oct) + (Charge, Nov) + (Charge, Dec) + (Charge, Yr2) + (Missing days * Avg daily charge) Missing days = (24 * Days in Period, Oct) - Days in Period for Oct through to end of timescale = (24 * 30) - (30 + 30 + 30 + 360) = 270 Avg daily charge = Charge for Oct to yr2/ Days from Oct to yr 2 = (30+40+40+400)/(30+30+30+360) = 510 / 450 = 1.1333 per day Invoice, Oct = 30 + 40 +40 +400 + (270 * 1.13333) = 816 The following example shows 24 periods in advance, starting in October, but replicates the last period to provide data for missing days.

Oct Y1
Expense No of Periods to Accumulate 30 24

Nov Y1 Dec Y1 Year 1 Year 2

40 0 40 0 300 12 400

In Advance / In Arrears Advance Days In Period Invoice Amount 30 30 30 810 360 0 360 0 810 0

User Guide 599

Chapter 12: Built in Functions (BiFs) Invoice, Oct = (Charge, Oct) + (Charge, Nov) + (Charge, Dec) + (Charge, Yr2) + (Missing days * Yr2 daily charge) =(30+ 40 + 40 + 400) + 270 * (400/360) = 510 + 300 = 810 If you leave the end conditions blank or set them to 0, Invoice = 510 and no data is provided for the missing days.

Steps to Use this BiF

1. Open the D-Cube to which you want to apply the @TimeSum BiF. The D-Cube must contain a calculation D-List and a timescale D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item to which you want to apply the @TimeSum BiF. 4. Click Change item attributes. 5. Click BiF. 6. Select TimeSum from the Function Name list. 7. Click Next. 8. In the BiF Function Wizard - Step 2 of 2 dialog box, enter your parameters. In the Items text box, select the type of items to appear: Detail, Calculated, or All. In the Items list, double-click the item to use as the expense amount to accrue.

The wizard moves the item to the Amount text box. Type the information in the remaining text boxes as shown in the following table. It is often easier to set up D-List formatted items for Arrears/Advance, End Conditions and the Days In Period Indicator so that the options selected can be viewed in the D-Cube.

Parameter
Periods

Description
The number of periods to add up to determine the size of the bill. For example: If you enter 3, the BiF accumulates three periods. This parameter reads the Advance/Arrears flag to determine whether to count the periods forward or backward. The current period is always included. @TimeSum processes the periods in chronological order, regardless of the sequence of the periods in the timescale D-List. No check is made to ensure that periods are contiguous and non-overlapping.

600 Analyst

Chapter 12: Built in Functions (BiFs)

Parameter
Arrears/Advance

Description
Whether to calculate the periods in advance or arrears. Valid values are: Blank = In arrears 1 = In arrears 2 = In advance

End

How to fill in missing data. Valid values are: 0 = Zero. this is the default setting; missing periods are treated as zero. 1 = Average 2 = Replicate 3 = Override. The override is used even if the number of periods is 0. 4 = Spare

Override Days in Period

Used when the End condition is set to 3 = Override. The length of period in days, used when the Indicator is set to 1 = Use Days in Period.

9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@TMax
Max = @TMax (Items) Input/Output Parameter
Items Input D-List Item

Description
Identifies the items that the maximum is taken over The maximum value for the selected items.

Result

How @TMax works

The @TMax BiF returns the maximum value of a specified list of items. For example, the following table shows the maximum values returned for the sample parameters one, two, and three. User Guide 601

Chapter 12: Built in Functions (BiFs)

Parameter
one two three max

Jan
10 10 20 20

Feb
20 50 60 60

Mar
60 30 60 60

Steps to Use this BiF

1. Open the D-Cube to which you want to apply the @TMax BiF. The D-Cube must contain a calculation D-List and a timescale D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to apply the @TMax BiF. 4. Click Change item attributes. 5. Click BiF. 6. Select TMax from the Function Name list. 7. Click Next. 8. Double-click an item to use for each Items parameter. 9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@TMin
Min = @TMin (Items) Input/Output Parameter
Items Result Input D-List Item

Description
Identifies the items that the minimum is taken over The minimum value for the selected items

How @TMin works

The @TMin BiF returns the minimum value of a specified list of items.

602 Analyst

Chapter 12: Built in Functions (BiFs) For example, the following table shows the minimum values returned for the sample parameters one, two, and three.

Parameter
one two three min

Jan
10 10 20 10

Feb
20 50 60 20

Mar
60 30 60 30

Steps to Use this BiF

1. Open the D-Cube to which you want to apply the @TMin BiF. The D-Cube must contain a calculation D-List and a timescale D-List. 2. Open the calculation D-List. 3. Click the Calculation cell of the item where you want to apply the @TMin BiF. 4. Click Change item attributes. 5. Click BiF. 6. Select TMin from the Function Name list. 7. Click Next. 8. Double-click an item to use for each Items parameter. 9. Click Finish. 10. Click Apply. 11. Save and close the D-List.

@Transform
The @Transform built in function helps users to build equations using angles and trigonometry functions when @Cycles does not provide the functionality that they need.

Input/Output
Input Method

Description
Methods: 0=No Change; 1=Sine; 2=Cosine; 3=Tangent; ...; 8=Degrees to radians; ... Input, varies with the method, for example: angle measured in radians.

Input

Input

User Guide 603

Chapter 12: Built in Functions (BiFs)

Input/Output
Result Output

Description
Transformations for time series.

Examples:
Radians=@Transform(8;degrees) Sine=@Transform(1;radians)

Methods
(0) output = input. (1) sine of angle measured in radians. (2) cosine of angle measured in radians. (3) tangent of angle measured in radians. (4) (1+input^2)^.5. (5) sinh of angle measured in radians. (6) cosh of angle measured in radians. (7) tanh of angle measured in radians. (8) convert from degrees to radians. (9) convert from radians to degrees. (-1) arcsin in radians of a number between + and - 1. (-2) arccos in radians of a number between + and - 1. (-3) arctan in radians. (-4) ((input^2)-1)^.5 for a number >1 or <-1. (-5) arcsinh in radians. (-6) arccosh in radians of a non-negative number. (-7) arctanh in radians of a number between + and - 1.

Note: When an input is outside of its range, then the output is zero, and no error message is generated.

604 Analyst

Chapter 12: Built in Functions (BiFs)

@TRound
Rounded=@TRound(Precision;Methods;Input) Input/Output Parameter
Precision Input Constant

Description
The decimal interval. 1 = To nearest integer 0.1 = To 1 decimal place 0.01 = To 2 decimal places 1000 = To nearest 1000 0.25 = To nearest quarter 12 = To nearest dozen

Methods

Input

Constant

The method of rounding. You can use uppercase or lowercase. C = (optional) (cumulate) cumulates the values along time, rounds the values, and then takes the difference. This method must be used in conjunction with one of the following methods: N = (nearest) rounds to the nearest whole integer. This is the default method. U = (up) rounds up to the nearest whole integer. D = (down) rounds down to the nearest whole integer. A = (away from zero) rounds a positive value up to the nearest whole integer and a negative value down to the nearest whole integer. T = (toward zero) rounds a positive value down to the nearest whole integer and a negative value up to the nearest whole integer.

Input

Input

D-List Item

The item with the values you want to round.

User Guide 605

Chapter 12: Built in Functions (BiFs)

How @TRound works

The @TRound BiF calculates the values for a specified input item using one or more rounding methods. These rounding methods allow you to round figures up, down, away from zero (up for positive numbers, down for negative numbers), or toward zero (down for positive numbers, up for negative numbers). You then can combine the rounding methods with a cumulative option that ensures that the result obtained by summing a series of rounded values (along a time dimension) is the same as summing a series of non-rounded values and then rounding the total.

Typical usage is as follows:

@TRound(Precision;U;Sales) @TRound(Precision;UC;Sales) @TRound(Precision;CU;Sales)

Decimal Intervals
The following table shows the decimal intervals allowed for the Precision parameter. To nearest integer To 1 decimal place To 2 decimal places To nearest 1000 To nearest quarter To nearest dozen 1 0.1 0.01 1000 0.25 12

Steps to Use this BiF

1. Open a D-Cube with a calculation D-List. 2. Open the calculation D-List. 3. Click the Calculation cell for the item you want to round. 4. Click Change item attributes. 5. Click BiF. 6. Select TRound from the Function Name list. 7. Click Next. 8. Double-click an item to use for the Precision parameter.

606 Analyst

Chapter 12: Built in Functions (BiFs) Note: If you enter a Precision parameter that varies over time, the input value is rounded in each period with the precision that applies in that period. If you combine this with method C, the cumulated values are rounded. The precision used to round the values in decimal interval form (1, 0.1, 0.01, and so on) is determined by the numeric format you defined for the Precision parameter. 9. Type the information in the remaining text boxes as shown in the following table.

Text Box
Methods

Description
The rounding methods to use. The method of rounding. The default method is N (nearest). You can use uppercase or lowercase. Select from the following: C (optional) (cumulate) cumulates the values along time, rounds the values, and then takes the difference. This method must be used in conjunction with one of the following methods: N (nearest) rounds the value to the nearest whole integer. U (up) rounds the value up to the nearest whole integer. D (down) rounds the value down to the nearest whole integer. A (away from zero) rounds a positive value up to the nearest whole integer and rounds a negative value down to the nearest whole integer. T (toward zero) rounds a positive value down to the nearest whole integer and rounds a negative value up to the nearest whole integer.

Input

The D-List containing the item values you want to round.

10. Click Finish. 11. Click Apply. 12. Save and close the D-List.

@Ytd
Year to Date = @Ytd (Original) Input/Output Parameter
Original Ytd Input BiF Result D-List Item D-List Item

Description
The original series Year to date result (Ytd Sales)

User Guide 607

Chapter 12: Built in Functions (BiFs)

How Ytd works

Ytd calculates year to date totals based on the original data. It starts accumulating again from scratch in the period containing the fiscal year start date; this is set within the options for the timescale D-List. Example: YTD Sales = @Ytd(Sales) uses a fiscal year start date of 1 April in the timescale D-List.

Jan
Sales YTD Sales 1000 1000

Feb
1000 2000

Mar
1000 3000

Apr
1000 1000

May
1000 2000

Jun
1000 3000

Formula used by Ytd

Ytd = Sum of original data from the start of the fiscal year.

Specify a year
A fiscal year start is required. Specify the day and month.

Steps
1. Open a timescale D-List. 2. From the D-List menu, click Options. 3. Click the Timescale tab. 4. In the Start of fiscal year boxes, set the day and month. 5. Save the timescale D-List.

Set up the Ytd calculation Steps

1. Create a calculation D-List. 2. Click the Calculation cell of the item to which you want to apply the BiF - in this case, Sales. 3. Click Change item attributes. 4. Click BiF. 5. Select Ytd from the Function Name list. 6. Click Next. 7. Double-click the parameters in the BiF Function Wizard. 8. Click Finish.

608 Analyst

Chapter 12: Built in Functions (BiFs) 9. Click Apply. 10. Save the D-List.

Switchover Dates
A switchover date is used by certain BiFs to define the dividing point between past and future. If the switchover date falls within or before a defined time period, that period is treated as a future period. If the switchover date occurs after the end of a defined time period, that period is treated as historic. The switchover date is used in the built-in functions, @Outlook, @Drive, @Drive1, @Drive2, @DCF, @ICF, @Mix, @Grow and @Stockflow. The switchover date is used to calculate a different result depending on whether a period is future or historic. Each built-in function contains its own logic on how to deal with switchover dates. BiFs typically use the first period as the default period if no date is specified. In the example shown, the switchover date was set to Jun 1, 1997 in the timescale D-List. June is therefore treated as a future period, May as the last historic period. Before the switchover date, the Forecast (the BiF result) is calculated as equal to History. After the switchover date, the Forecast is calculated to reflect the impact of a predicted cost driver. (Forecast, Jun) = (History, May) * (Driver, Jun)/ (Driver, May) (Forecast, Jul) = (History, May) * (Driver, Jul)/ (Driver, May), and so on. For example, @Drive1 could have an input parameter named D-List to use the switchover date in the D-List. Forecast = @Drive1(History;Dlist;Driver;Effect) You can override the D-List switchover date in the BiF formula by defining the switchover parameter as a fixed date, todays date, a period number, or leaving it blank in the BiF formula.

Bif Parameter Definition

19970501 Set the switchover date to May 1, 1997. Treat May as a future period, April as a historic period. If you use a generic monthly D-List containing the items Jan, Feb, Mar, and so on, the program looks at the period number and ignores the year. 5 denotes May. Use the period number for generic monthly timescale D-Lists only (D-Lists containing the items Jan, Feb, Mar, and so on). This option is not available if you define periods by dates. Use todays date Use the switchover date as defined in the timescale D-List. Treat all timescale periods as historic.

Today Dlist None

User Guide 609

Chapter 12: Built in Functions (BiFs)

Examples:
Forecast = @Drive1(History;19970501;Driver;Effect) Forecast = @Drive1(History;5;Driver;Effect) Forecast = @Drive1(History;Today;Driver;Effect) Forecast = @Drive1(History;Dlist;Driver;Effect) Forecast = @Drive1(History; ;Driver;Effect)

Set up a Switchover Date in a Timescale D-List

Steps
1. Open the desired timescale D-List. 2. From the D-List menu, click Options. 3. Select Use Switchover. 4. In the box below Use Switchover, type a date. 5. Ensure that you define from and to dates for each period. The only exception is to use the standard months Jan, Feb, Mar, and so on. 6. Click OK. Note: Priority on Switchover Dates A switchover date used as a parameter in a built in-function formula (for example, 19970501) has priority over a switchover date in a timescale D-List. If you want to use the latter, you must enter the word, Dlist, in the built in-function formula. 7. After setting up the BiF, open the calculation D-List and edit the BiF formula. Note: To refer to the switchover date in the timescale D-List, edit the BiF switchover date parameter to read Dlist. 8. Save the D-List.

Set up a Switchover Date in a BiF Formula

You can set up a switchover date in the BiF formula rather than the timescale D-List. The parameter in the BiF formula can be Today, the period number, or a specific date (in the format yyyymmdd) . The switchover date in the BiF formula has priority over the switchover date in the D-List.

Steps
1. Open the calculation D-List. 2. Click the Calculation cell of the item containing the BiF. 3. Click Change item attributes. 4. Type the switchover date as a parameter in the formula. 610 Analyst

Chapter 12: Built in Functions (BiFs) Note: If you leave the date parameter blank, all time periods will be treated as historic. 5. Save the D-List. Note: Ensure that you define from and to dates for each period in the timescale D-List. The only exception to this is to use the standard months, Jan, Feb, Mar, and so on, which the switchover date recognizes.

Print or Preview BiF Specifications

See (p. 42) to print or preview the specifications of certain BiFs.

User Guide 611

Chapter 12: Built in Functions (BiFs)

612 Analyst

Chapter 13: Macros

When performing the same operations repeatedly in Cognos Planning - Analyst, you can automate the operations using a macro. A macro is a set of commands that have been recorded and grouped together as a single command, which is used to automatically complete a list of instructions in one step. Analyst allows most operations that a user can perform to be recorded and automated in the form of macro functions. Typical examples of simple macro functions are @DCubeOpen (p. 669), which opens a D-Cube, and @DLinkExecute (p. 662), which executes a D-Link. Examples of more complex macros include the creation and maintenance of selections of D-Cubes and the maintenance of D-Lists from multiple sources. Macro functions may have one or more parameters. For example, @DCubeOpen requires a parameter that specifies which D-Cube to open. Most parameters can be entered using a selection from a drop down box.

Analyst Macro Example Libraries

You can download working examples of some Analyst macros to supplement the documentation. They are available from the Cognos support Web site (http://support.cognos.com), in the Documentation downloads section. Search for Type of Document: Utility Macro functions are grouped as follows: D-List (p. 627) ODBC (p. 650) Control (p. 650) D-Link (p. 662) D-Cube (p. 669) File Map (p. 704) A-Table (p. 706)

Creating and Running Macros

It is always good practice to start and finish macros on a blank screen. Most macros require objects to which they refer to be open and active. In these cases it is a good idea to insert the action of opening the object as part of the macro itself so that it is not reliant on other macros or operations

User Guide 613

Chapter 13: Macros to operate correctly. Macros can then be built, which automate sub processes and which operate together using the @MacroExecute command. Steps: Create a macro in one of the following ways: Write a new macro by picking the @macro function from a menu and filling in the parameters. Start a recording (p. 615), and go through the actions needed, and then stop the recording and save the macro. Most macros can be recorded however a few must be manually written.

Execute a saved macro, (p. 615).

Create a Macro using the Wizard

Use the macro wizard to create a new macro. If you want to use recent commands in a macro, you can copy macro compatible commands from the transcript.

Steps
1. From the Tools menu, click Macros, New Macro. 2. Click Insert. 3. Select an object type from the Group list on the left. 4. Select a macro from the Function list on the right. Tip: To use commands from a transcript of recently used commands, click Tools, Macros, Edit Transcript. 5. Click Next. The next steps will vary according to the macro you have chosen. In most cases you must click Edit. Analyst will then bring up a dedicated dialog box or sequence of dialog boxes that allow you to modify the parameter. 6. Enter the parameters (if necessary). 7. Click Finish. 8. Move the macro in the list using the Move Up and Move Down buttons. 9. Click Close, and then name and save the macro. The name of the macro should describe the main purpose of the macro. It is recommended that prefix abbreviations are used for the most common macros. For example DCU DCubeName DLO DListName Updates D-Cube Opens D-List

614 Analyst

Chapter 13: Macros

DLU DListName MUM ModelName

Updates D-List Updates whole or part of a model

Record a Macro
Recorded macros always create a new macro. When you have finished recording the command lines can be cut, copied and pasted to other macros using Edit commands.

Steps
1. From the Tools menu, click Macros, Record. 2. Record the commands that you wish to go into the macro by carrying out the operation. 3. Click Stop when you have finished. The macro editor shows the steps you have recorded. 4. Save and name the macro.

Run a Macro
Execute a macro to complete an automated task. It is good practice to use the trace feature to test macros before using them in live environments. Macros can be documented using the @Rem command as well as entering Description and Notes in the summary information.

Steps
1. From the Tools menu, click Macros, Run. 2. Select the macro you want to run, and then click OK.

Macro Editor
The macro editor allows you to create and edit macros, allows multiple step insertion, copy & paste within and between macros, tracing, and more control on text parameters. Multiple macro windows can be opened and the user can open D-Cubes, D-Lists, A-tables, and other objects directly from the right-click menu.

Editing Macro Code

The following tasks occur in the macro code tab of the macro editor. The macro code consists of a series of macro commands set up to run in a specific order.

Steps to edit a macro

1. From the Tools menu, click Macros, Open Macro.

User Guide 615

Chapter 13: Macros 2. Select the macro name, and then click OK.

Steps to add new steps to the macro

1. Click Insert on the line you want to enter a new step or command. 2. Select a macro function and set its parameters. 3. Follow the dialog boxes as directed. 4. Click Finish to return to the Code page. 5. When you have finished editing a macro, click Close. 6. Click Yes when prompted to save the macro.

Steps to remove macro steps

1. Select the step or command you wish to delete. 2. Click Delete. 3. When you have finished editing a macro, click Close. 4. Click Yes when prompted to save the macro.

Steps to copy and paste macro commands

1. Open a macro and highlight the steps in the source macro. 2. From the main menu, click Edit, Copy (or Cut, if appropriate). 3. Open the target macro and position the cursor. Choose Edit, Paste and the steps will be inserted immediately above the cursor position. Once copied, the steps can be edited as usual.

Steps to reorder the sequence of steps in which the macro operates

1. Select a function (or block of functions) and use the Move Up and Move Down arrow buttons to reorder the sequence in which the macro functions run. 2. When you have finished editing a macro, click Close. 3. Click Yes when prompted to save the macro.

Steps to edit a parameter value

1. Highlight the parameter you wish to edit, click the Edit parameter button and change the value. Tip: If you right-click the Edit button in the macro editor, you can open any object called by the macro. 2. When you have finished editing a macro, click Close. 3. Click Yes when prompted to save the macro.

616 Analyst

Chapter 13: Macros Parameters can be replaced by an input variable to be defined by the user at run-time) or a constant value. 4. To use a variable (or constant) in a parameter you must first define the variable then right click on the Parameter box, select Use Variable and choose the variable from the drop-down menu. 5. When you have finished editing a macro, click Close. 6. Click Yes when prompted to save the macro.

Step to use the macro trace facility

Trace through a macro a step at a time, or skips steps, open a macro and choose Macro>Trace. If you have no macro open, use Tools>Macros>Trace Macro and select a macro.

Command
Back Trace Go Skip Exit and Abort

Resulting Action
Selects the previous step. Allows the user to step through the macro, one step at a time. Continues the macro right to the end. Skips the current step. Cancels the macro at the current step.

Steps to insert multiple steps

1. Create a new macro using Tools, Macro, New (or edit an existing macro). 2. Select Macro, Wizards, choose Multiple Insert, and then click OK. 3. Select the macro from the list of available macros, and then click Next. 4. Select the objects and use the arrow keys to order the objects. This is the order the steps will appear in the macro, although it can be changed later. Click OK. Tip: You can use of the Macro Wizard to create a global update using a series of @DcubeUpdate steps. 5. Click Finish. 6. Save and name the macro.

Editing Macro Variables

Constant Variables allow the same argument to be provided for several functions in a macro without typing it in repeatedly.

User Guide 617

Chapter 13: Macros Input Variable allow a user to define a parameter to go into a macro at run-time. The types of input variables are different for each macro.

Input and Constant Variables in Macros

There are two types of variables used in macros: Inputs and Constants. Constant variables: A constant variable is hard-coded into the macro and is used throughout the macro. It can only be changed by editing the macro and a user is not prompted to change it at run-time. To create a constant variable, right-click the Edit button on the Parameter box at the bottom of the Code page of the macro editor and choose Variable from Value. Click on the Variables tab to see the definition of the constant variable. You can change the name and definition of the new constant variables as well as insert new variables and delete unused variables. Input variables: At run-time, the macro will prompt you at run-time for details of the parameter defined here. The input variable could be a text string, an integer or an object name. It is important to note that the parameter is only used in this step. There is no facility to enter an input variable at run-time and use this for all the steps in the macro.

Steps to insert an input variable into a macro command

1. Open the Macro. 2. Click the Variables tab. 3. Select Inputs from the drop-down list. 4. Click Insert and then select a variable type from the list. 5. Enter a default value for the variable. 6. Optionally, you may choose to edit the name for the variable in the Name dialog box, or the user prompt in the Prompt box. 7. Click the Code tab. 8. Select the macro command. 9. Right-click the Edit button at the bottom of the Code page of the macro editor and choose Use Variable, then select the appropriate variable from the list. 10. Save and close the macro. When the macro is run, you will be prompted for an input variable.

Steps to convert an input variable back to a value

1. Open a macro and move the cursor down to the command where the macro is used.

618 Analyst

Chapter 13: Macros 2. Right-click the Edit button and choose Value from Variable. The variable will be replaced with the default value of the variable. You may edit this to put your own value.

Steps to edit message fields in macros

1. Open a macro which uses the message parameter, highlight the @message line and move the cursor down to the text field in the lower part of the macro editor. 2. Right-click and select Zoom. A text box allows you to edit text and messages in macros. Use this feature to change the message text only. 3. You can cut, copy, paste and delete by using the right-click in the zoom window.

Steps to print nested macros

1. Open the macro. 2. Select File, Print and click the Macros tab. Select the Expand @MacroExecute option on the Macro tab.

Start a Macro With Batch Utility Wizard

Use the Analyst Batch Utility wizard to create a batch job to start Analyst macros when a computer is unattended.

Configure Analyst Security

To configure Analyst security, there are a number of steps you can take. 1. Configure integrated Windows authentication if you want to execute macros without interaction. 2. Specify a default library. 3. Assign access at object, library, or item level. Note: If there is more than one namespace configured, you can define the namespace in the Batch Scheduler wizard. For more information on configuring security, see "Security" (p. 45).

Run the Batch Utility Wizard

The wizard lets you easily create or modify a batch job. From the Analyst Tools menu, select Batch Utility Wizard.

User Guide 619

Chapter 13: Macros

Create a Batch Job

If you want to create a new batch job, you must select a library that contains the macro you want to run, and then select the macro.

Steps
1. Select Create a new batch job. The Select a macro page shows the previous macro selection, if applicable. 2. From the Select a library drop-down menu, select a library that contains the macro you want to run. 3. From the Select a macro drop-down menu, select the macro you want to run. 4. In the Name the batch job field, enter a name for your batch job. A default name is provided, which includes the library and macro name. You can change this to be anything you like. The name must be unique and not in use. 5. Optional: Click View details if you want to see the actual steps of the macro. 6. Specify a log file for the output messages. You need to choose a valid folder for the output file location. 7. The Finish page summarizes the macro information. You may print the summary. 8. Click Finish to run the batch job.

Modify a Batch Job

If you want to modify or delete an existing batch job, you must select a library that contains the batch job you want to modify or delete, and then select the batch job.

Steps
1. Select Modify or delete an existing batch job. 2. From the Library drop-down menu, select a library that contains the batch job you want to modify or delete. Only libraries that have existing batch jobs will be listed. 3. From the Batch job drop-down menu, select the batch job you want to modify or delete. Click Delete if you want to delete the batch job. Click Yes to delete the selected batch job and all of its associated files.

4. If you want to modify an existing batch job click Next. 5. The Select a macro page shows the batch job information for you to modify, except you cannot change the batch job name. 6. Select a new library and or macro to run under the existing batch job name. 7. Optional: Click View details if you want to see the actual steps of the macro.

620 Analyst

Chapter 13: Macros 8. Modify the log file for the output messages if desired. You need to choose a valid folder for the output file location. 9. Click Next. 10. The Finish page summarizes the macro information. You may print the summary. 11. Click Finish to run the batch job.

Using the Command Line to Run a Macro or Batch Job

You can run macros and schedule Analyst batch jobs from the command line using the batch utility CepBatch.exe. The CepBatch.exe program is installed in <installation_location>\cognos\c8\bin. You can transfer modeling and data from Cognos Finance and Cognos Performance Applications to Analyst from the Analyst command line. You can also access and run Analyst macros using the following methods: Create an Analyst macro, create a Batch Utility Job using the macro, and paste the command line to an outside scheduler or to a command prompt to run the job. Type a series of parameters and arguments into a command prompt or create a batch file to run a macro without creating a batch file.

Steps
1. Open a command window (or DOS window), and type: cd C:\Program Files\cognos\c8\bin. 2. Type: CepBatch. 3. Type the command line to run a macro or batch job. All arguments containing special characters or spaces must be in double quotes.

Command Line Options

The table below defines the options, you can use from the command line and the parameters applicable to each option. You must enclose all arguments containing special characters in double quotation marks. Each argument has a number associated with it.:

Options
-m

Definitions
Runs any Analyst macro using the library number Runs any Analyst macro using the library name

Parameters
-1 LibNo -2 Macro_Name -5 Namespace -6 Language -7 Log_File -1 LibName -2 Macro_Name -5 Namespace -6 Language -7 Log_File

-m0

User Guide 621

Chapter 13: Macros

Options
-u1

Definitions

Parameters

Runs a macro that updates -1 LibName -2 D-ListName -5 a D-List from its IQD Namespace -6 Language -7 e.List text source file -8 generate new ID Runs a macro updates the IQD Mapping Table Runs a macro that upgrades a D-List created from a pre-Cognos Planning 7.3 MR1 release Runs a Batch Utility job -1 LibName -2 D-ListName -5 Namespace -6 Language -1 LibName -2 D-ListName -5 Namespace -6 Language -7 D-List type -8 Date format -9 Full e.List -10 e.List export file -1 Job_Name

-u2

-u3

-b

Command Line Examples

Run Macro Using Library Number (-m)
Use this command to run an Analyst macro, specifying the library number.

Syntax
CepBatch -m -1 LibNo -2 MacroName -5 Namespace -6 Language -7 LogFile

Structure: Parameter
LibNo MacroName Namespace Language

Description
library number macro name Namespace Language code: EN = English FR = French DE = German Specifies the languages of error messages and messages in a message box

Required/Optional
Required Required Required Optional. If omitted the default of EN is used.

LogFile

Full file path to a log file

622 Analyst

Chapter 13: Macros

Run Macro Using Library Name (-m0)

Use this command to run an Analyst macro specifying the library name.

Syntax
CepBatch -m0 -1 LibName -2 MacroName -5 Namespace -6 Language -7 LogFile

Structure Parameter
LibName MacroName Namespace Language

Description
library name macro name Namespace Language code: EN = English FR = French DE = German Specifies the languages of error messages and messages in a message box.

Required/Optional
Required Required Required Optional, if omitted the default of EN is used

LogFile

Full file path to a log file

Update D-List from IQD (-u1)

Use this command to update a D-List from its IQD source. Item names, hierarchies and display orders will be in sync with the IQD source.

Syntax
CepBatch.exe -u1 -1 LibID -2 D-ListName -5 Namespace -6 Language -7 e.List text file -8generate new ID]

Structure Parameter
LibID

Description
Library Name

Required/Optional
Required

User Guide 623

Chapter 13: Macros

Parameter
D-ListName

Description
Name of the D-List. The D-List must be created from an IQD through an earlier wizard session, otherwise the macro will fail. Namespace Language code: EN = English FR = French DE = German Specifies the languages of error messages and messages in a message box

Required/Optional
Required

Namespace Language

Required Optional. If omitted the default of EN is used

e.List text file generate new ID

Full path for the e.List output text file. Optional. Applies to e.Lists only Non-zero ID. Optional

Example
To execute a command line in OS sign-on mode:
CepBatch -u1 -1 1094000 -2 SAP_EList -7 c:\Program Files\My elists\elist.txt

To execute a command line in OS sign-on mode and rebuild a D-List with new ID's:
CepBatch -u1 -1 1094000 -2 SAP_EList -7 c:\Program Files\My elists\elist.txt -8 1

Update IQD Mapping Table (-u2)

Use this command to run a macro to synchronize an IQD mapping table with an Analyst D-List.

Syntax
CepBatch.exe -u2 -1 LibID -2 D-ListName [-5 Namespace] [-6 Language]

Structure Parameter
LibID

Description
Library Name

Required/Optional
Required

624 Analyst

Chapter 13: Macros

Parameter
D-ListName

Description

Required/Optional

Name of the D-List. The D-List Required must be created from an IQD through an earlier wizard session, otherwise the macro will fail. Namespace Language code: EN = English FR = French DE = German Specifies the languages of error messages and messages in a message box. Required Optional, if omitted the default of EN is used

Namespace Language

Example
To execute a command line in OS sign-on mode:
CepBatch -u2 -1 1094000 -2 SAP_FP

Upgrade D-List Created From an Earlier Release (-u3)

Use this command to run a macro to upgrade a D-List from a pre-Cognos Planning 7.3 MR1 release.

Syntax
CepBatch.exe -u3-1 LibID -2 D-ListName[-5 Namespace[-6 Language][-7 D-List type][-8 Date format][-9 Full e.List][-10 e.List export file]

Structure Parameter
LibNo D-ListName Namespace

Description
Library Name Name of the D-List Namespace

Required/Optional
Required Required Required

User Guide 625

Chapter 13: Macros

Parameter
Language

Description
Language code: EN = English FR = French DE = German Specifies the languages of error messages and messages in a message box

Required/Optional
Optional, if omitted the default of EN is used

D-List type

D-List Type

0 - Normal D-List (Default) 1 - Timescale D-List 2 - e.List

Date format

Date Format - only valid with Timescale D-List

0 for "mm/dd/yyyy hh:mm:ss" (Default) 1 for "yyyy-mm-dd hh:mm:ss" 2 for "dd-mm-yyyy hh:mm:ss" 3 for "yyyymmdd"

Full e.List

A non-zero digit needed to create a Required full e.List The full path of the e.List export file Required

e.List export file

Example
To execute a command line in OS sign-on mode:
CepBatch -u3 -1 1094000 -2 SAP_PFrtm -6 1 -7 3

Run a Batch Job (-b)

Use this command to run a batch utility job.

Syntax
CepBatch -b -1 JobName

Parameter
JobName

Description
Batch utility job name

Required/Optional
Required

626 Analyst

Chapter 13: Macros

D-List Macros
D-List macros deal with macro functions relating to D-Lists. The following table shows whether the D-List needs to be open and be the active object to work. If a macro command requires an active object but can not find one, the command will not work.

Macro name
@DListNew @DListOpen @DListUpdate @ExportToEList @ItemDelete @DListItemImportCognosPackage @DListItemCopyFromDList @DListItemImportDelimitedText @DListItemImportFileMap @DListItemImportFinance @DListItemImportDCube @DListItemImportIQD @DListItemImportOdbc @RefreshDataWarehouse

Requires active object?

No No No No Yes Yes Yes Yes Yes No Yes No Yes No

@DListNew
This D-List macro creates a new, unnamed D-List with no items. The D-List cannot be saved until some new D-List items have been added. It has no parameters to enter.

To use this macro

1. From the Tools menu, click Macros, New Macro.

User Guide 627

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click DListNew in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Finish. 2. Move the macro in the list using the arrows (if necessary). 3. Close the macro. You will be prompted to name and save the macro. Click Yes. 4. Name and save the Macro and click OK. Note: When you run this macro, you will have to define the D-List.

@DListOpen
This D-List macro opens the specified D-List.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click DListOpen in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DList. 2. Select a Library and D-List from the Select or Create New D-List dialog box, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

628 Analyst

Chapter 13: Macros

@DListUpdate
This D-List macro updates the specified D-List from the Import Link defined in the D-List.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click DListUpdate in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DList. 2. Select a Library and D-List from the Select or Create New D-List dialog box, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK. This macro will run all relevant D-Links into the D-List.

@ExportToEList
This D-List macro automates the export a D-List in Analyst into a format the Contributor Administration Console can import into an e.List.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click ExportToEList in the Function list.

User Guide 629

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click Edit DList. 2. Select a Library and D-List from the Select or Create a New D-List dialog box, and then click OK. 3. Click Edit File. 4. Enter the filename, or browse for the filename for the target file to export. 5. Click Finish. 6. Move the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

@ItemDelete
This D-List macro removes the specified items from the D-List The target D-List must be open and must be the active object to run this command.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click ItemDelete in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit List and then type the D-List item name from the D-List. 2. Repeat for the remaining D-List items that you want to delete, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

630 Analyst

Chapter 13: Macros

Item Import Macros

The @DListItemImport macros (@DListItemImportCognosPackage, @DListItemCopyFromDList, @DListItemImportDelimitedText, @DListItemImportFileMap, @DListItemImportFinance, @DListItemImportDCube, @DListItemImportIQD, @DListItemImportOdbc) update any D-List from one or multiple sources. The sources available are: Cognos package D-List Delimited Text File Map Cognos Finance D-Cube IQD ODBC source

The normal import options, Append or Update (with or without RemoveObsolete) are available in these macros. If the import mode is set to Update with RemoveObsolete enabled, the Keep option allows the user to specify certain items to be retained in the D-List even if they no longer appear in the source data. When importing from a D-List there is an option to import formats, formulas and calculation options with each item. The item import functions require the target D-List to be open and the active object.

Import Modes
The combination of inputs for Import Mode and Keep means that there are four possible rules for the import which apply to all the ItemImport functions.

Append
New items may be added to the list but old items are never removed from the D-List or from calculations. Existing descriptions, formats or calculation objects will not be changed. If a unique code has been defined, items in the source with a unique code the same as that of an existing D-List item will be rejected and the description will not be updated.

Update with the RemoveObsolete Check Box Cleared

New items in the source file will be added to the list. If a unique code has been defined, the description part of the D-List item will be updated if new data appears in the source. When importing from hierarchical tables the hierarchy will also be updated. Items not found in the source remain in the list. If an item not found in the source is part of a sub-total, it will remain with

User Guide 631

Chapter 13: Macros its parent. Thus a hierarchy may be updated from a source file containing only part of the hierarchy. The exception to this is importing from a D-List, with the option to import the formula for the subtotal - in this case the formula for the updated item will be exactly as in the source list.

Update with the RemoveObsolete Check Box Selected

The hierarchy in the D-List being updated will be completely updated with that found in the source file. Items no longer in the source will be removed from the list. Sub-totals in the list will be amended to remove items removed by the import. Other calculations which require variables not found in the source will be removed. Formats and Weighted averages will be removed unless importing from another D-List when they will be updated in accordance with the source data.

Update with the RemoveObsolete Check Box Selected but Keep Certain Items
Specified D-List items may be kept even if they no longer appear in the source. Provided that the Keep items are no longer in the source, their formats will be preserved, as will their calculation options unless they are set as weighted averages, weighted by items no longer in the source. Formulas of Keep items will be unchanged provided all of their variables are still found in the updated list. Subtotals will be amended to remove items no longer in the source unless they too have been specified as items to keep. Other calculations which no longer have all their variables available will be removed. If the source file points an item which is part of a Keep subtotal to a new parent, it will be a part of the new subtotal and the keep subtotal in the updated list.

Import to a Specified Sub-total

When specifying a sub-total in which imported items are to be included, it is important to define the import in such a way as to ensure the specified subtotal will remain in the list after import. If Update mode is used, with RemoveObsolete enabled and the specified sub-total is not found in the source, it should be specified as a Keep item. If the specified subtotal is not found in the updated list, a warning messages notifies you that item X is no longer a member of the D-List and that the calculation on the item cannot be updated as specified, where X is the sub-total specified in the import definition. This message is not suppressed even if the import is part of a macro which automatically saves the updated D-List.

@DListItemImportCognosPackage
This macro will import items into a D-List from a Cognos package. You need to create a model and publish a Cognos package before you can use the @DListItemImportCognosPackage macro. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, use of RemoveObsolete will not normally be appropriate in this situation. To use this macro the Target D-List must be open and active therefore the macro @DListOpen should immediately proceed it.

632 Analyst

Chapter 13: Macros

Parameters CognosPackageData
You select data from a Cognos package and specify how you should map columns to attributes.

Mode
The import mode can be set to Update or Append.

Locations
This defines the location and sort order for the newly imported items. Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If RemoveObsolete is selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed.

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-List items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is selected. If you have decided to keep a total, it can still have its formula modified. Sometimes it is necessary to update a formula because its variables no longer exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

User Guide 633

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportCognosPackage in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit PackageData. You need to select the Cognos package data and tell it how to map the columns to the attributes. 2. Select a package from the drop box. 3. Select a Query Subject. 4. Under the Available Query Items in selected Query Subject list, select the available Query Items in the Query Subject and move them to the Selected Query Items pane. 5. Select the Display preview of selected query items check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. Click OK. 6. In the Specify import data screen, you can specify how to map the columns to the attributes. Select an attribute from the drop down menu, for example Skip, Item Name, Parent, etc., and then click OK. 7. Select import mode Update or Append by clicking on the drop down arrow of the Mode box. 8. Select the location of the new items and the sort order of the D-List by clicking on the drop down arrow of the Location box and selecting the option required. 9. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>. 10. Select the RemoveObsolete check box to remove items no longer in the source file, or clear the RemoveObsolete check box to retain them in the target D-List. This option will not function if the import has been defined in Append mode. 11. Click the Edit DListSelection to select the D-List you are updating from the list which appears. Click the Edit Selection button and highlight the items you wish to keep by clicking on them and then click Move>> to select them. Click OK to leave the selection screen. Even if you do not wish to use the Keep function, it is necessary to complete this parameter to finish the macro. Click the Edit D-List selection button and select the D-List you are updating from the list which appears. Do not select any items, simply click OK to leave the selection screen.

634 Analyst

Chapter 13: Macros There is no Empty Selection Means All Items here. If no D-List items are selected, none will be kept in the updated list unless they appear in the source file. 12. Click OK to confirm your D-List selection. 13. Click Finish. 14. Save and name your macro before closing.

@DListItemCopyFromDList
@DListItemCopyFromDList(Selection; Mode; Location; Total; RemoveObsolete; Keep; Detail; Calculated; Format; Formulas). This macro imports items, formulas, and formats from one D-List into another. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, use of RemoveObsolete will not normally be appropriate in this situation.

Parameters Selection
The source D-List name and items to be imported. An open selection will import all items - subject to the settings below.

Mode
The import mode can be set to Update or Append. Append adds to the list of items, but never removes items from D-Lists. Simple subtotals can be amended by the addition of new items, but old items in subtotals do not get removed. Append mode will not change formats or descriptions. Update updates the list of items and, if a unique code portion has been defined, updates the item description. Update will also update simple subtotals if you import replacement formulas from another D-List. If an item in a simple subtotal has a new parent, then the item is moved from the old subtotal to the new one. This is the primary difference between Update mode and Append mode. In Append mode, existing subtotals do not get altered, whereas in Update mode, an item can be moved from an old subtotal to a new one. More complex formulas involving any of the other operators (- * / % IF THEN ELSE) will not get updated, although new complex formulas can be copied in. If the complex formula does not have all the variables it needs, it gets converted to a comment (preceding//) and a warning is issued. This warning is suppressed while running macros.

Location
This defines the location and sort order for the newly imported items.

User Guide 635

Chapter 13: Macros Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise, choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If RemoveObsolete is selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed.

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-list items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is cleared. If you have decided to keep a total, it can still have its formula modified. Sometimes it is necessary to update a formula because its variables no longer exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List.

Detail
1=Import detail items 0=Import no detail items (default)

Calculated
1=Import calculated items 0=Import no calculated items (default)

Format
1=Import format specifications 0=Do not import format specifications (default)

Formulas
1=Import formulas belonging to the items imported 0= Do not import formulas (default)

636 Analyst

Chapter 13: Macros

Create the Macro

It is usually easier to record this macro and then edit individual parameters on the command line if required.

Steps
1. From the Tools menu, select Macros, and then click Record. 2. Open the Target D-List. 3. From the D-List menu, select Add Items, click Copy From D-List, and select the D-List. 4. If you want to copy all items, leave the selection blank (open selection) and click OK, otherwise, select the items you want to copy in and click OK. 5. Select the Import mode, and select where you want to position the new items. Optionally, you can choose to import just detail items, just calculated items or both. You may also choose to copy in the format attribute and the formulas of the items you are copying. 6. Optionally, you may choose to turn this into a permanent update which can be run whenever you choose D-List, Update. The advantage of recording it in a macro is that you can update a single D-List from several sources, so you will probably want to choose No at this stage. 7. Click Stop to stop recording the macro. 8. Save and name the macro.

@DListItemImportDelimitedText
This macro will import items into a D-List from delimited text files. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, use of RemoveObsolete will not normally be appropriate in this situation. To use this macro the Target D-List must be open and active therefore the macro @DListOpen should immediately proceed it.

Parameters TextDataMap
You select a delimited text file and specify a delimiter. You then specify how to map the columns to attributes.

Mode
The import mode can be set to Update or Append.

Location
This defines the location and sort order for the newly imported items.

User Guide 637

Chapter 13: Macros Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If RemoveObsolete is selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed.

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-List items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is selected. If you have decided to keep a total, it can still have its formula modified. Sometimes it is necessary to update a formula because its variables no longer exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List. Create the Macro (p. 613). A D-List has to be the active object for this command to work.

Using {LIB} Parameter

In the first step of the Macro Wizard Step 2, you can use the {LIB} parameter to make the file path dynamic. On the edit or creation of the macro step, the {LIB} parameter will refer to the folder where the macro is saved. However as there has to be an open active D-List for this macro step to operate at runtime, when the macro runs, {LIB} will refer to the folder where the open active D-List is saved. It both the D-List that is to be updated, and the macro that contains the update step are stored in different libraries, it is recommended that you place an identical copy of the source file in each location. If the macro is unsaved, then on creation or edit, the {LIB} parameter will be the location of your default library.

Steps to use this macro

1. From the Tools menu, click Macros, NewMacro.

638 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportDelimitedText in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit TextDataMap. Click Select. Enter the path to the delimited text file, or click Browse and navigate to the file you require. From the drop-down box, select a delimiter to apply to the text file. Click OK. Select a column and then click the drop-down menu to select an attribute to map to that column. Repeat for each column. You must, at minimum, select an Item name.

2. Select import mode Update or Append by clicking on the drop down arrow of the Mode box. 3. Select the location of the new items and the sort order of the D-List by clicking on the drop down arrow of the Location box and selecting the option required. 4. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>. 5. Select the RemoveObsolete check box to remove items no longer in the source file, or clear the RemoveObsolete check box to retain them in the target D-List. This option will not function if the import has been defined in Append mode. 6. Click the Edit DListSelection to select the D-List you are updating from the list which appears. Click the Edit Selection button and highlight the items you wish to keep by clicking on them and then click Move>> to select them. Click OK to leave the selection screen. Even if you do not wish to use the Keep function, it is necessary to complete this parameter to finish the macro. Click the Edit D-List selection button and select the D-List you are updating from the list which appears. Do not select any items, simply click OK to leave the selection screen. There is no Empty Selection Means All Items here. If no D-List items are selected, none will be kept in the updated list unless they appear in the source file. 7. Click OK to confirm your D-List selection. 8. Click Finish. 9. Save and name your macro before closing.

User Guide 639

Chapter 13: Macros

@DListItemImportFileMap
This macro will import items into a D-List from mapped text files. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, use of RemoveObsolete will not normally be appropriate in this situation. To use this macro the Target D-List must be open and active therefore the macro @DListOpen should immediately proceed it.

Parameters FMapDataMap
You select a mapped text file and specify how to map the columns to attributes.

Mode
The import mode can be set to Update or Append.

Location
This defines the location and sort order for the newly imported items. Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If RemoveObsolete is selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed.

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-List items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is selected. If you have decided to keep a total, it can still have its formula modified. Sometimes it is necessary to update a formula because its variables no longer

640 Analyst

Chapter 13: Macros exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List. Create the Macro (p. 615). A D-List has to be the active object for this command to work.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportFileMap in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit FMapDataMap. Click Select. Choose a Library and then select the File Map you require. Click OK. Select a column and then click the drop-down menu to select an attribute to map to that column. Repeat for each column. You must, at minimum, select an Item name.

2. Select import mode Update or Append by clicking on the drop down arrow of the Mode box. 3. Select the location of the new items and the sort order of the D-List by clicking on the drop down arrow of the Location box and selecting the option required. 4. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>. 5. Select the RemoveObsolete check box to remove items no longer in the source file, or clear the RemoveObsolete check box to retain them in the target D-List. This option will not function if the import has been defined in Append mode. 6. Click the Edit DListSelection to select the D-List you are updating from the list which appears. Click the Edit Selection button and highlight the items you wish to keep by clicking on them and then click Move>> to select them. Click OK to leave the selection screen. Even if you do not wish to use the Keep function, it is necessary to complete this parameter to finish the macro. Click the Edit D-List selection button and select the D-List you are updating from the list which appears. Do not select any items, simply click OK to leave the selection screen. There is no Empty Selection Means All Items here. If no D-List items are selected, none will be kept in the updated list unless they appear in the source file. 7. Click OK to confirm your D-List selection.

User Guide 641

Chapter 13: Macros 8. Click Finish. 9. Save and name your macro before closing.

@DListItemImportFinance
This macro will import items into a D-List from Cognos Finance. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, use of RemoveObsolete will not normally be appropriate in this situation.

Parameters Cognos Finance

The selection of data from a Cognos Finance system, including a dimension, submission, and sub selection of items. You may also set naming rules for the imported items. You can preset all the fields on this screen by selecting a template file, or you can manually set it up. Note: Once the fields have been pre-selected using the template file, the system ignores the template file, and only stores the settings on the screen, so there is no dynamic behavior if you afterwards change a Cognos Finance template file that has been used to specify an import.

Mode
The Import mode can be set to Update or Append.

Location
This defines the location and sort order for the newly imported items. Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise, choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If RemoveObsolete selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed 642 Analyst

Chapter 13: Macros

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-List items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is selected. If you have decided to keep a total, it can still have its formula modified. Sometimes it is necessary to update a formula because its variables no longer exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List. Create the Macro (p. 615). A D-List has to be the active object for this command to work.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportFinance in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box click Edit FinanceData. Select a Cognos Finance system, a dimension, submission, sub-selection of items, and naming rules for import items. 2. Select import mode Update or Append by clicking on the drop down arrow of the Mode box. 3. Select the location of the new items and the sort order of the D-List by clicking on the drop down arrow of the Location box and selecting the option required. 4. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>. 5. Select the RemoveObsolete check box to remove items no longer in the source file, or clear the RemoveObsolete check box to retain them in the target D-List. This option will not function if the import has been defined in Append mode. 6. Click the Edit DListSelection to select the D-List you are updating from the list which appears. Highlight the items you wish to keep by clicking on them and then click Move>> to select them. Click OK to leave the selection screen. Even if you do not wish to use the Keep function, it is necessary to complete this parameter to finish the macro. Do not select any items, simply click OK to leave the selection screen. There is no Empty Selection Means All Items here. If no D-List items are selected, none will be kept in the updated list unless they appear in the source file.

User Guide 643

Chapter 13: Macros 7. Click OK to confirm your D-List selection. 8. Click Finish. 9. Save and name your macro before closing.

@DListItemImportDCube
This macro will import items into a D-List using a single page from a D-Cube as the source. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition, as the use of RemoveObsolete will not be appropriate in this situation.

The Source D-Cube

Items to be imported to the D-List consist of either the rows D-List and a number of data columns, or a number of data columns within the D-Cube. The D-Cube may also contain other columns and pages not needed for the import. If the D-List forming the rows of the source cube contains formula items, these will be ignored for the purpose of the import, and only detail items will be imported.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportDCube in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit DCubeDataMap. Click Select, and choose a library and D-Cube. Click OK to select all pages, or select specific pages to import and then click OK. Map columns to attributes. Select a column, then from the drop-down menu select an attribute. You must, at minimum, select an Item name.

2. Select import mode Update or Append from the Mode box. 3. Select the location of the new items and the sort order of the D-List from the Location box. 4. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>.

644 Analyst

Chapter 13: Macros 5. Zero suppression can be applied to the rows of the cube if needed. Enter a 1 in the SuppressZeroRows field to switch on zero suppression, otherwise leave as zero. This feature allows conditional selection of items to be imported. This can be achieved as follows: Include conditional formula in the Source D-Cube to identify appropriate hierarchical information (for example all items belonging a specific group). If only the appropriate columns are selected in the D-Cube Selection with zero suppression on then the cube only opens with those items which meet the criteria met by the conditional formula. The resulting D-List is only updated by those items. 6. If the Update mode has been selected, the RemoveObsolete check box may be selected or cleared if this function is required. Select the check box to have items no longer in the source cube selection removed from the updated D-List. This option will not function if the import has been defined in 'append' mode. If this function is enabled, D-List items no longer present in the source cube selection are deleted from the D-List with the result that any data held against them in D-Cubes will be lost. Note: RemoveObsolete will not function if the D-List being updated forms the rows D-List in the source D-Cube. 7. If you have defined an import in Update mode with the RemoveObsolete check box selected, it is possible to select existing items in the D-List to keep, even if they are no longer in the source cube selection. If you have decided to keep a sub-total, it can have its formula modified on import, either by adding new items or by removing detail items which no longer appear in the source cube selection. 8. Keep. Even if you do not use the Keep function, it is necessary to complete this parameter to finish the macro. Click Edit DListSelection and select the D-List you are updating from the list which appears. Do not select any items, click OK to leave the selection screen. To define which items should be kept when using the Update with the RemoveObsolete check box selected: Click Edit DListSelection. Select the D-List from the list which appears. Highlight the items you wish to keep by clicking on them and then click Move>> to select them. Click OK to leave the selection screen.

9. Click OK to confirm your D-List selection. 10. Click Finish. 11. Save and name your macro before closing.

@DListItemImportIQD
This macro lets you import D-List items from IQD data. This macro can only be used to maintain a D-List that has originally been created from the IQD import. User Guide 645

Chapter 13: Macros

Parameters DList
This button lets you choose the D-List to be updated from IQD data. The D-List must have been created using the IQD Import in Analyst.

NewIIDs
Select this check box to assign new IIDs and GUIDs to all items when the import runs.

EListFile
This is where you may optionally enter the location where the EList import data should be stored. If this field is empty, the original file specified at creation time will be used.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportIQD in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit DList. Select a library and D-List that you want to be updated from IQD data. 2. Click OK. 3. Select the NewIIDs check box if you want to assign new IIDs to all items when the import runs. 4. Optional: In the EListFile box, enter the location where you want the EList import data to be stored. 5. Click Finish. 6. Save and name your macro before closing.

@DListItemImportOdbc
This macro will import items into a D-List from an ODBC source. A D-List can be updated from more than one source by using a series of @DListItemImport macros instead of an update link. When importing from multiple sources, care must be taken with the import definition.

646 Analyst

Chapter 13: Macros Use of RemoveObsolete will not normally be appropriate in this situation.

Create the Macro

An ODBC DSN (Data Source Name) must have been set up in the ODBC Driver Setup dialog box. The Data Source Name is the name in which the user gives his ODBC connection. To use this macro the Target D-List must be open and active therefore the macro @DListOpen should immediately proceed it.

Parameters OdbcDataMap
This dialog lets you select an ODBC Source and specify a SQL statement. You then map the columns to attributes.

Mode
The Import mode can be set to Update or Append.

Location
This defines the location and sort order for the newly imported items. Bottom, Top, Select, Alphabetical, Hierarchical, Totals After/Calc, Totals Before/Calc, Totals After/ A-Z, Totals Before/A-Z, Totals After/Z-A, Totals Before/Z-A, Totals After/None, Totals Before/ None.

Total
If you want all the items to go into a single subtotal you can pick a subtotal, otherwise, choose None or Allocate. If you choose Allocate then the user can choose which subtotal(s) the new items are included in at run time.

RemoveObsolete
Check box selected = yes Check box cleared =no When update mode has been chosen, a check box allows you to decide whether to remove obsolete items. If the RemoveObsolete check box is selected, then obsolete items get removed from the list and their associated data is lost. Items included in more complex formulas or in existing weighted averages would never get removed automatically. It is only items in simple sub-totals that can be removed.

Keep
A selection of D-List items to keep. If mode=Update and the RemoveObsolete check box is selected, you can allow certain D-List items to be kept, even though they are not present in the source list. The Keep button only appears if the RemoveObsolete check box is selected. If you have decided to keep a total, it can still have its User Guide 647

Chapter 13: Macros formula modified. Sometimes it is necessary to update a formula because its variables no longer exist in the D-List. Keep will not preserve the formula, format or its calculation option, but will ensure it remains in the D-List.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @DListItemImportOdbc in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Edit Parameters dialog box, click Edit OdbcDataMap. 2. Click Select. 3. Double-click an ODBC source. You can view the available tables and columns. Select the Display system tables check box if you want to view the system tables. Type in the SQL Statement that is required to retrieve the correct data, and then click Fetch. Or you can click CreateSQL to create a new SQL statement. You can preview the columns. Click OK.

4. Enter a user id and password to make the initial connection to the database. The correct string is uid=xxxx;pwd=yyy. 5. Select or clear the Keep connection open check box. It is selected by default. 6. Under Driver options, type in the SQL statement required to retrieve the correct data. 7. Click Connect. 8. You now need to Map columns to attributes. This identifies which column in the source cube selection contains each level of the hierarchy. Select a column under View of raw import columns, then from the drop-down menu select an attribute. Repeat for all hierarchy levels. Valid hierarchy attributes are INames, Parent, Parent2, Parent3, Parent4, Parent5, Parent6, Parent7, Parent8. 9. Click OK. 10. Select import mode Update or Append from the Mode box.

648 Analyst

Chapter 13: Macros 11. Select the location of the new items and the sort order of the D-List by clicking on the drop down arrow of the Location box and selecting the option required. 12. Complete the Total parameter if you wish to specify an existing sub-total into which new items should be allocated. If this field is left blank, it will be interpreted as <None>. 13. Select the RemoveObsolete check box to remove items no longer in the source file, or clear the RemoveObsolete check box to retain them in the target D-List. This option will not function if the import has been defined in Append mode. 14. Click Edit DListSelction to select the D-List you are updating from the list which appears. Do not select any item, simply click OK to leave the selection screen. There is no empty selection means all items here. If no D-List items are selected, none will be kept in the updated list unless they appear in the source file. 15. Click OK to confirm your D-List selection. 16. Click Finish. 17. Save and name your macro before closing.

@RefreshDataWarehouse
This macro will update Planning dimensions from D-Lists that are created in the Performance Applications data warehouse. The credentials to access the Performance Applications database are not specified in the macro. Instead, the database connection names used by IQD must be created through Cognos Connection.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-List in the Group list. 2. Click @RefreshDataWarehouse in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DList to select the D-List to be written back to the Data Warehouse. 2. Select a Library and D-List from the Select or Create New D-List dialog box, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary).

User Guide 649

Chapter 13: Macros 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

ODBC Macros
@ODBCConnect, @ODBCClose
@ODBCConnect connects to an ODBC source as part of a macro and @ODBCClose closes the open ODBC source. Only one ODBC source can be open at any time. @ODBCConnect is used to log on and open an ODBC source. The source remains open until and @ODBCClose command is run or Analyst is shut down. The DriverOptions parameter specifies the ODBC source name and driver options supported (e.g username and password (uid=xxxx;pwd=yyy)). If the datasource for ODBC requires a user name and password to log on, then these must be specified in the macro in the driver options box in the format uid = xxxx; pwd =yy. You must also specify the username and password in the format uid = xxxx; pwd =yy in the driver options box of the ODBC logon screen in the object using the odbc connection (allocation table, D-Link or D-List import link). @ODBCClose has no parameters because it closes the active ODBC source, and only one source can be open at a time.

Control Macros
Control macros deal with macro functions that control the flow of execution of a macro, or apply to several types of objects. @Activate (p. 651) @AddLocalPreSelection (p. 651) @CheckAccess (p. 652) @CheckAccessLevel (p. 653) @Close (p. 653) @Delay (p. 653) @FileTranslate (p. 653) @LibCopy (p. 654) @MacroExecute (p. 655) @Message (p. 656) @PackDir (p. 656) @PackDirSel (p. 657) @Rem (p. 658)

650 Analyst

Chapter 13: Macros @Reset (p. 658) @Run (p. 658) @Save (p. 660) @ShutDown (p. 660) @TestData (p. 660) @UnPackDir (p. 661)

@Activate
This control macro makes a specified object active when several objects are open in the Analyst window. The first parameter (Edit Object) specifies the object to become active. For D-Cubes, the second parameter (View) defines the section view to be activated. Enter 1 in all cases where the D-Cube is only open once. If you have multiple views of the same D-Cube open, then enter the integer which identifies the view you wish to activate.

Steps to create this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click Activate in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit Object. 2. Select an object to be activated and then click OK. 3. For D-cubes only, enter an integer in the View box. 4. Click Finish. 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@AddLocalPreSelection
The purpose of this macro command is to permit a reduced selection of D-List items at the macro run time. If you put it at the start of a macro before a series of @DCubeOpen macros, it only opens the reduced selection of the D-Cube. Therefore, it can be used to perform a global update on a slice

User Guide 651

Chapter 13: Macros of the model. This can be useful when you are nearing the volume limit imposed by the memory limits on your PC or you want to improve the time taken to update large models. It can also be used to control how much of a D-Cube is exported in an export data macro.

Parameters Selection
Enter the name of the preselection. Generally, this is not used anywhere and is purely there for reference purposes. If there are two AddLocalPreselection steps in the same macro that both refer to the same D-List and if the two preselections have the same name, the later AddLocalPreselection step replaces the first. If however they have different names, and refer to the same D-List, the later AddLocalPreselection step is ignored.

PreSelection
Selection of one or more items from a single D-List. If an input variable is used in the PreSelection then the user can define the items to be included in the PreSelection at run time.

@CheckAccess
@CheckAccess(Objects, Maxdelay) The CheckAccess macro is used to ensure that the user has exclusive write-access to a list of objects, prior to continuing with a macro. Typically, it will be used at the start of a global update macro to prevent other users from opening objects that are in the process of being updated. When a macro reaches a CheckAccess step, the program attempts to gain exclusive write-access to the objects listed. It only releases the write-access when the macro ends or you exit from the macro. While the macro is running, this will prevent other users from opening these objects in write-mode, although they can still open them read-only. If users already have the objects open, the macro will wait for a given number of minutes (defined in MaxDelay), to give them time to save and close their work. However it will not force them or notify them to close the objects. If the time runs out, and the macro has not got the exclusive write-access to all the objects listed, the macro will cancel.

Parameters Objects
A list of objects chosen from the library screen.

MaxDelay
Enter the number of minutes the macro should wait while it is waiting for other users to close the objects.

652 Analyst

Chapter 13: Macros

@CheckAccessLevel
@CheckAccessLevel(Objects, Level, Lock, Maxdelay) The CheckAccessLevel macro will check whether the user has the specified access level to a selected list of objects. If the Boolean flag Lock is set, it will also write lock these objects as is done by the CheckAccess macro. You may want to have several CheckAccessLevel steps in the beginning of a macro so you can check each step of the macro for a specific access level. Each macro step can only check for one access level, which is why multiple steps may often be necessary. For example, you may want to have Read access to D-Cubes used as the source for a D-Link run in the macro, and Write access to target D-Cubes.

Parameters Objects
A list of objects chosen from the library screen.

Level
The access level to check for. Select Read, Write, or Control.

Lock
Select the check box if you want to lock objects.

MaxDelay
Enter the number of minutes the macro should wait while it is waiting for other users to close the objects.

@Close
This control macro closes the active object. The parameter, Option, consists of text, which can be empty, Y, or N. If empty, the user is prompted with the prompts that the system normally asks during the execution of this operation. If Y or N, then yes or no is used as the response buttons to all prompts.

@Delay
This control macro pauses for a specified number of seconds before continuing with the next command.

@FileTranslate
This control macro translates a file named InFile, writing the result to OutFile, using the named section in file TransFile as a translation table. The translation file can be created in any simple word editor (e.g. Notepad or Wordpad) and should contain a section that looks like this: User Guide 653

Chapter 13: Macros [UK ASCII] 156=163; US Pound Sign To obtain the ASCII numbers refer to an ASCII code table. The characters after the colon character are an optional description. This instructs the system to leave all codes except ASCII 156, which is the pound sign, as they are, and to translate 156 into 163, which is the ANSI or Windows pound sign.

Parameters InFile
Enter the full path and name of the source file to be translated. All sections of the filepath/name must be a maximum of 8 characters and must not include spaces.

OutFile
Enter the full path and name of the resultant file. All sections of the filepath/name must be a maximum of 8 characters and must not include spaces.

TransFile
Enter the full path and name of the translation file containing the translation rules. All sections of the filepath/name must be a maximum of 8 characters and must not include spaces.

Section
Enter the section name of the translation file.

@LibCopy
This control macro copies an entire library into another library for a selection of detailed items in a D-List. It is unusual to include this macro command as more comprehensive options exist within the Analyst Library functions.

Steps to create this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click LibCopy in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter the library number of the source library to be copied in the Source box. 654 Analyst

Chapter 13: Macros 2. Enter the library number of the target library to be copied to in the Target box. The number you enter does not have to be a library number which is already defined on your system. 3. Optional: Enter a path of a target folder. If no path is entered, the path to the library in step 2 will be used. When specifying the path in the TargetDir box, specify either a folder which is not currently defined as an Analyst library or the path to the folder for the library you specified in step 2. If you define a path to a folder which is already used as an Analyst library with a different number you will not be able to open the copied objects without redefining your libraries. 4. Click Edit DListSelection and then make a selection from the appropriate D-List. The input variable, Selection, is the restriction to be applied to data being copied. It consists of a D-List selection that allows you to create an accumulation model, and then send out a slice of that model to a subsidiary. The subsidiary model is the same as the main accumulation model except that the selection defines a reduced D-List. Note: In the case of this macro, an empty selection does not mean select all items, so if you leave the selection as an open selection, then the macro will copy all the objects but you will not be able to open any D-Cube which uses the D-List defined in the selection parameter. You must therefore select at least 1 detail item. Do not select calculated items to be copied unless every detail item required for the calculation has also been selected, because, if you do, cubes in the target library containing this selection D-List will display calculation errors. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

@MacroExecute
This is a control macro designed to run a set of other macros in a specified order. Important: Be careful not to select the macro itself when selecting a macro to execute otherwise the macro will run all the commands up to the @MacroExecute line twice before exiting.

Parameters Macro
Select the macro to execute from a library.

Steps to Expand Nested Macros that use @MacroExecute

1. Open a macro and go down to the @MacroExecute step.

User Guide 655

Chapter 13: Macros 2. Right-click the Edit Macro button in the lower half of the macro editor and select Open it to view the steps.

Steps to print out a nested macro in full:

1. Open the macro. 2. From the File menu, select Print and click the Macros tab. Check the Expand MacroExecute option. 3. Click Print.

@Message
This control macro displays a message in a Windows Message box and waits for user to respond. If the buttons parameter is empty or O, it displays an OK button only. If YN or OC are specified, this macro displays Yes/No or OK/Cancel buttons (respectively). If the user selects No or Cancel the macro will terminate.

Parameters Message
Enter the text of the message you wish to display. After entering this command, you can edit the message by right clicking on the message line at the bottom of the screen and selecting zoom. You can then press Enter in the text to give multi-line text boxes.

Buttons
Select from the drop down box or leave blank.

@PackDir
This control macro creates an archive file. The parameter, PackFile, is the archive file name and path to be created. The parameter, Directory, is the path of the directory to pack. The Options feature is not currently available. The file created is a PK zip file (Win32 bit version) and the files can be unzipped using the @UnPackDir macro. The macro command can be used to zip up the contents of folders which are not Analyst libraries.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click PackDir in the Function list.

656 Analyst

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Enter the name and path of the archive file to be created in the Packfile box. If no path is specified then the archive file will be saved in the system folder of the installation. 2. Enter the path of the source to be archived in the Directory box. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK. 7. To access the archived file, refer to the @UnPackDir macro.

@PackDirSel
This control macro creates an archive file with a subset of the files contained in a specified directory. The parameter, PackFile, is the archive file name and path to be created. The parameter - Directory, is the path of the directory to pack. The Options feature is not currently available. The parameter, FileList, is the list of filenames to pack. The file created is a PK zip file (Win32 bit version) and the files can be unzipped using the @UnPackDir macro. The macro command can be used to zip up the contents of folders which are not Analyst libraries.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click PackDirSel in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter the name and path of the archive file to be created in the Packfile box. If no path is specified then the archive file will be saved in the system folder of the installation. 2. Enter the path of the source directory to be archived in the Directory box. 3. Click Edit List, and then specify the files to be archived. Click OK. 4. Click Finish.

User Guide 657

Chapter 13: Macros 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK. To access the archived file, refer to the @UnPackDir macro.

@Rem
This control macro creates a comment consisting of a string of characters. It is used for placing comments in the macro code and does not display during the running of the macro. It can be left blank.

@Reset
This control macro resets the active object. The parameter - Option, can be empty, Y, or N. If empty, the user will be prompted with the prompts that the system would normally ask during the execution of this operation. If Y or N, and then yes or no will be used as the response buttons to all prompts.

@Run
This macro runs a .exe file from within Analyst.

Parameters Pathname
The full pathname of the application you want to run. @Run allows you to use the {LIB} and {LIBNO} parameter in the path, in place of the current library path and library number. At run-time, the path where the macro is saved will be used instead of the {LIB} parameter. Similarly, it will use the library number instead of the parameter {LIBNO}. If you store the application (.exe file) in the same location as the @Run macro, this allows you to move models around without having to worry about hard-coding the path of the application.

Params
An optional parameter that would usually follow the .exe file in the command line. The {LIB} and {LIBNO} functions can be used in this parameter.

Options
The options Exit, Pause or Continue define what to do after you exit from the application.

Exit
On running the .exe file the macro cancels. Continue On running the .exe file continues to the end of the macro without a prompt. 658 Analyst

Chapter 13: Macros Pause On running the .exe file pauses the macro temporarily and puts up a message.

Message
You can put an optional text message to appear when exiting from the application, provided you use the Pause option. The Message box appears with two buttons - Yes or No. If you choose Yes, the macro will continue. If you choose No, the macro will cancel at this point.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click Run in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter the path to the application to be run in the Pathname box. The LIB and LIBNO parameters may be used. 2. Optional: Enter the parameters in the Params box. 3. Enter either Exit, Pause, or Continue in the Options box. 4. If you have used the Pause option at step 3, you may enter a message in the message box if required. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. 8. Name and save the Macro and click OK.

Examples
The Continue parameter indicates that on exiting from an application the macro will continue without a prompt. The path must be in double-quotes if spaces exist in the path. @Run(""C:\Program Files\MyApplication.exe""; "";"Continue";"") If the .exe file is stored in the same folder as the @Run macro you can use the {LIB} parameter to pick up on the library path name. User Guide 659

Chapter 13: Macros @Run(""{LIB}\MyApplication.exe""; "";"Continue";"") An example of the Pause parameter shows how the full path is not always needed. For example, to start notepad, then pause on exit, with the message 'Carry on?' use the following syntax: @Run("notepad";"";"Pause";"Carry On?") An example of the Exit parameter shows how to start Internet Explorer and go to the Cognos website. The Exit parameter means that when you exit from Internet explorer, the macro will stop. @Run("iexplore.exe","www.cognos.com","Exit","") To open an Excel spreadsheet named myfile.xls, note the use of the parameter containing the spreadsheet name. The path must be entered in single-quotes. The @Run macro will change it to double quotes automatically. @Run("excel.exe";"""C:\Program Files\Cognos\myfile.xls""";"Exit","" ) Using the {LIB} parameter, the program replaces {LIB} with the current library path at run-time. In the example shown, it opens an Excel file named myfile.xls, found in the directory of current library. Note that double quotes are needed round the file parameter. @Run("excel.exe";"""{LIB}\myfile.xls""";"Exit","" )

@Save
This control macro saves the current active object. The parameter - Option, can be empty, Y, or N. If empty, the user will be prompted with the prompts that the system would normally ask during the execution of this operation. If Y or N, then yes or no will be used as the response buttons to all prompts.

@ShutDown
This control macro shuts down Analyst. The parameter - Option, can be empty, Y, or N. If empty, the user will be prompted with the prompts that the system would normally ask during the execution of this operation. If Y or N, and then yes or no will be used as the response buttons to all prompts.

@TestData
This control macro allows you to test a selection of data before continuing. If data in the selection passes the test, macro execution continues; if data does not pass the text, the macro stops. The two last parameters allow you to specify messages to be displayed to the user, restart the macro or exit from the macro in either case.

Parameters Data
Defines a selection of a D-Cube to be tested.

Expression
The Expression parameter is a string in one of the following forms: 660 Analyst

Chapter 13: Macros ZERO ALL f value ANY f value If you use the keyword ZERO, all data in the selection must be zero. The keywords ALL or ANY should be followed by one of the operators >, <, =, <=, >=, or <>, and then a single numeric value. As an example, to test whether all cells in the specified selection are less than 1000, use the string expression: ALL < 1000 As an example, to test whether all cells in the specified selection are zero, use string expression: ALL = 0 or ZERO

MsgOK
The message to be displayed if the criteria in the expression parameter is met. Alternatively &Restart will restart the macro from the beginning or &Exit will exit from the current macro.

MsgFail
The message to be displayed if the criteria in the expression parameter is not met. Alternatively &Restart will restart the macro from the beginning or &Exit will exit from the current macro.

&Restart and &Exit

If you type &Restart in the MsgFail parameter, whenever the criteria fails to be met, the macro restarts at the beginning of the current macro. When the criteria is met, it looks at MsgOK. At that point, &Exit will exit from the current macro. If you leave it blank, it will continue with the current macro. If you put a normal text message in, it will pause and wait for user input. Because macros can be called from other macros, this lets you do a Do...Until loop.

@UnPackDir
This control macro unpacks an archive file into a specified directory. The parameter, PackFile, is the archived file name and path to be unpacked. The parameter, Directory, is the path of the destination directory to unpack to. Options should be set to keep to keep existing files, substituting when a match is found. The Options parameter Keep or Substitute can be entered, or if the box is left blank (the default), all files in the destination Directory will be deleted prior to unpacking the PackFile.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

User Guide 661

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click Control in the Group list. 2. Click UnPackDir in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter the name and path of the file to be unpacked in the Packfile box. 2. Enter the path of the directory to which the file will be unpacked in the Directory box. 3. Enter Keep or Substitute in the Options box. Keep leaves existing files in the folder before unzipping, but overwrites the files if there is a clash with existing files. Substitute deletes files before unzipping.

4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

D-Link Macros
D-Link macros deal with macro functions relating to D-Links. The following table shows whether the D-Link needs to be open and be the active object to work. If a macro command requires an active object but can not find one, the command will not work.

Macro name
@DLinkActivateQueue @DLinkExecuteInv @DLinkExecSel @DLinkExecute @DLinkExecuteList @DLinkNew 662 Analyst

Requires Active Object

No No No No No No

Chapter 13: Macros

Macro name
@DLinkOpen @DLinkSelectList

Requires Active Object

No Yes

@DLinkActivateQueue
When linking between Analyst and Contributor, and targeting the production application, this D-Link macro activates a Contributor import queue that executes a D-Link from Analyst to apply data to a cube.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkActivateQueue in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit Application to select an application in which to activate the import queue. 2. Click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@DLinkExecuteInv
This D-Link macro executes a D-Link inversely. For example, it transfers data from the Target to the Source cube.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

User Guide 663

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkExecuteInv in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DLink. 2. Select a D-Link. 3. Click OK. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

@DLinkExecSel
This macro runs a D-Link into a selection of the target D-Cube.

Parameters
Link - identifies the D-Link to run TargetSelection - specifies a selection of the target D-Cube Source - should be left empty

Alternatively, you can use a macro to open the selection of the D-Cube first then use a DLinkExecute command.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkExecSel in the Function list.

664 Analyst

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click Edit DLink. 2. Select a D-Link, and then click OK. 3. Click Edit DCubeSelection. 4. Select the Target D-Cube, and then click OK. 5. Make a selection of the D-Cube, and then click OK If you want the user to make the selection of the D-Cube during the macro execution then you should use an input variable allowing the user to choose a selection from the Target D-Cube. 6. Click Finish. 7. Move the macro in the list using the arrows (if necessary). 8. Close the macro. You will be prompted to name and save the macro. Click Yes. 9. Name and save the Macro and click OK.

@DLinkExecute
This macro runs one D-Link. To update a series of D-Cubes, you can create a macro consisting of a set of @DLinkExecute commands in a particular order, alternatively you could use the macro command @DCubeUpdate which will run all the D-Links in the update table of a D-Cube.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkExecute in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DLink. 2. Select a D-Link, and then click OK. 3. Click Finish.

User Guide 665

Chapter 13: Macros 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK. An alternative to the above procedure is to record a macro. You should record only the actions you want played back in the macro. For example, normally you will want to run D-Links without restricting the target area, and save the data transferred to the target D-Cube without confirmation. When recording a macro, you do not need to open the target D-Cube, run the D-Link, then save the D-Cube. You can run the D-Link into the entire target D-Cube and have the changes saved automatically by clicking the Tools menu, and then clicking Run Target Link, or by running the D-Link from the Object Library dialog box.

Open target D-Cubes when running D-Links in a macro

If you use a series of @DLinkExecute commands to run a batch of D-Links into one D-Cube, each @DLinkExecute command opens the target D-Cube with the smallest possible selection (the target area), runs the D-Link, and then saves the D-Cube.

@DLinkExecuteList
This macro is designed to run a series of D-Links in order. The @DlinkExecuteList macro behaves exactly the same as a series of @DlinkExecute steps, except where the source is Contributor data. In this case, when the macro runs the first D-Link, it logs the time and takes a consistent read of the Contributor database. All subsequent D-Links that have the same Contributor source use the data from that point in time rather than the actual time when the D-Link is run. This ensures consistency across D-Links coming from the same Contributor data source. If a subsequent D-Link in the macro has a different Contributor data source, the old source is closed and the new one opened. Similarly, if you have two @DlinkExecuteList steps in the same macro or in a sub-macro called via a @MacroExecute step, each time the old data source is closed and the new one opened. You should therefore include all links from the same Contributor datasource within a single @DLinkExecuteList command. Only a list of D-Links is required as a parameter by this command. You may include any set of D-Links, whether they are normal Analyst D-Links, Analyst > Contributor, or Contributor < Analyst D-Links.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

666 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkExecuteList in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ListofDLinks. 2. Select the D-Links, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@DLinkNew
This D-Link macro creates a new D-Link. There are no parameters used in this command.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkNew in the Function list. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK. Note: When you run this macro, you will have to define the D-Link.

User Guide 667

Chapter 13: Macros

@DLinkOpen
This D-Link macro opens the specified D-Link. The only parameter required is the D-Link name.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkOpen in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DLink. 2. Select a D-Link in the Select or Create New D-Link dialog box, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@DLinkSelectList
This D-Link macro opens a D-Link and selects a dimension (D-List or file-column) to be active. The D-Link must be the active object for this command to work therefore you should precede this command by @DLinkOpen.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Link in the Group list. 2. Click DLinkSelectList in the Function list.

668 Analyst

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Look at the box labeled TS. Enter T to make the target side active or S for the source side. 2. Enter the name of the D-List which you want to make active in the List box. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

D-Cube Macros
D-Cube macros deal with macro functions relating to D-Cubes or views of D-Cubes. The following table shows whether the D-Cube needs to be open and be the active object to work. If a macro command requires an active object but can not find one, the command will not work.

Macro name
@DCubeCalculate @DCubeClearMask @DCubeCommand @DCubeCreateDSels @DCubeCreateTSels @DCubeDeleteSels @DCubeDeselect @DCubeExport @DCubeIncreaseSelect @DCubeInput @DCubeLoadFormat

Requires active object?

Yes Yes Yes No No No Yes Yes Yes Yes Yes

User Guide 669

Chapter 13: Macros

Macro name
@DCubeNew @DCubeOpen @DCubeOpenChooseSel @DCubeOpenNamedSel @DCubeOpenSelect @DCubePage @DCubePageId @DCubePrint @DCubeReselect @DCubeSort @DCubeTranspose @DCubeUpdate @GenerateTransformerModel @Publish PrintAll SliceCommand SliceUpdate

Requires active object?

No No No No No Yes Yes Yes Yes No Yes No No No Obsolete use @DCubePrint No No

@DCubeCalculate
This D-Cube macro performs all outstanding calculations on the current D-Cube view. A D-Cube must be the active object in order for this command to work.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

670 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeCalculate in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Finish. (No entry is required in the Type box). 2. Move the macro in the list using the arrows (if necessary). 3. Close the macro. You will be prompted to name and save the macro. Click Yes. 4. Name and save the Macro and click OK.

@DCubeClearMask
This D-Cube macro clears all Holds, Protections or Locks from an entire D-Cube. A D-Cube must be the active object in order for this command to work and must be fully open. If you want to clear all locks, protects and holds from a D-Cube, then you will have to have three separate @DcubeClearMasks commands, each clearing a different type of mask.

Parameters Mask
Type of mask (Holds, Prots or Locks)

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeClearMask in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter Holds (to clear all holds) or Prots (to clear all protections) or Locks (to clear all locks 2. Click Finish.

User Guide 671

Chapter 13: Macros 3. Move the macro in the list using the arrows (if necessary). 4. Close the macro. You will be prompted to name and save the macro. Click Yes. 5. Name and save the Macro and click OK.

@DCubeCommand
The purpose of this macro is to apply a specified command to a specified selection. The selection must be a subset of the current selection applied to the current view. This macro is similar to the @DCubeCmd macro with the exception that this macro contains an extra parameter named Empty. The Empty parameter defines whether the empty selection should apply only to all detail items or include all totals as well. If the selection is left empty and the Empty parameter is set to detail, the command is applied to all detail items. If the Empty parameter is set to all, the command is applied to all total and detail items. When recording this macro, the Empty parameter defaults to all for commands Protect, Unprotect, Lock, and Unlock and detail for commands Hold, Release, and other commands with the following exception: if the targeted empty dimension contains only totals, the command is applied to all the totals no matter what was set for the Empty parameter.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeCommand in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter The command into the Input parameter 2. Enter either DETAIL or ALL in the Empty parameter 3. Select a D-Cube and the selection which will be affected by the macro. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

672 Analyst

Chapter 13: Macros

@DCubeCreateDSels
This D-Cube macro is used to create and maintain one or more saved selections for a specific set of cubes, based on D-List-formatted data stored in one column of a D-Cube. This macro automatically overwrites (updates) pre-existing saved selections with the new definitions as derived by the macro specification. The unique identification of a saved selection is only the saved selection name. The parameters Totals, Data, Cubes, Lists, and Permanent must be edited at least once in order to set up the macro.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeCreateDSels in the Function list. 3. Click Next.

Macro Wizard Step 2

1. The first item to be defined is which items from a D List are going to be used to create the selections. In the Totals row, click Edit DListSelection and then select the D-List items on which you want to create the selections. You make a selection of items (normally Detail items) in a D-List. The selected D-List must be used as the D-List formatting list in a column of a D-Cube. A saved selection is created for each selected item in Totals, as long as the item actually appears in at least one cell in the appropriate column of the Data D-Cube, for each cube selected in Cubes parameter below. Each saved selection's name will be the same as the Totals item name subject to the Prefix, Suffix, and CubeName parameters (optional). 2. In the Data row, click Edit DCubeSelection and then select the items. The cube selection must be a single page of D-Cube showing only a D-List in the cube (as Rows) and a single column showing the Totals information. This column (that is, the D-List item that forms the column label) must be D-List-formatted by the D-List specified under Totals. 3. In the Cubes row, click Edit ObjectList and then select the Target D-Cubes. The D-Cubes you select are the ones for which saved selections are to be created. 4. In the Lists row, click EditObjectList and then select the D-Lists.

User Guide 673

Chapter 13: Macros Here you select a set of one or more D-Lists. Each of the target cubes chosen in Cubes must use only one of the D-Lists in Lists. Generally, each of the D-Lists in Lists will contain at least some items that match against items in the row D-List of the D-Cube slice. Lists can include or consist of only the row D-List of the D-Cube slice. 5. In the Parents row, enter the number of parents. The integer you enter indicates the number of hierarchical levels (parents) to be included automatically in each saved selection. The parent items are derived individually in each saved selection for each cube of D-Cubes by reverse expanding the items initially included in the saved selection as a result of the Totals/Data/List matching mechanism. 6. In the Permanent row, click Edit List and then type the set of text strings. The text strings you type should match exactly the D-List item names of items that are to be included in all saved selections. If no permanent items are required, the set should be completely empty, but the permanent button must be defined as empty to complete the macro command. For each cube in the Cubes parameter, a different D-List in the Lists parameter might apply. It is not possible to specify here a selection of D-List items from a particular D-List. Instead, a set of text strings can be defined, which, for each target cube in the Cubes parameter, is matched against the appropriate D-List of the Lists parameter. This generates additional items to be included in the saved selections. If for each cube in the Cubes parameter, for a particular String in the Permanent parameter, no match is found in the appropriate D-List of the Lists parameter, this item will not appear in the saved selections for that D-Cube. 7. In the Prefix box, type a prefix. The prefix is an optional text string, attached automatically to the front of every saved selection name, which can be used in conjunction with a suffix. 8. In the Suffix box, type a suffix. The suffix is also an optional text string, attached automatically to the end of every saved selection name, which can be used in conjunction with a prefix. 9. In the CubeName box, enter an integer between -31 and 31 (zero can be used). The integer you enter specifies the number of characters from the front of the respective cube name that also will be used in the saved selection name. The value zero (0) indicates that no characters will be used. A positive value indicates that the respective number of characters, counting from the beginning of the cube name, will be inserted before the Totals name but after the prefix (if any). A negative value indicates that the respective number of characters, counting from the beginning of the cube name, will be inserted after the total name but before the suffix (if any). When created, CubeName characters within the saved selection name are always contained in parentheses.

674 Analyst

Chapter 13: Macros Care must be taken when creating saved selections for more than one cube to avoid duplicate saved selection names. If the number of characters selected in this parameter results in duplications then saved selections using duplicate names will be created and only the saved selections for the last cube defined in the Cubes parameter will be saved. 10. In the Spacer box, enter a spacer character. The spacer is a character used to separate the CubeName part from the Totals part in the resulting Saved Selection Name. 11. Click Finish and if necessary move the macro in the list using the arrows. 12. Close the macro. You will be prompted to name and save the macro. Click Yes.

Additional Notes
This macro only creates saved selections for D-List items specifically selected from the D-List in Totals. If no items are selected in Totals, the macro attempts to create saved selections for all items in the D-List (empty selection equals all). However, a saved selection is not created for any item (whether explicitly or implicitly selected) if that item does not appear in any cell of the respective column of the D-Cube. If a saved selection previously existed for such an item, this macro actually deletes that saved selection. For example, if the macro is attempting to create a saved selection for an item in Totals, but that item does not appear anywhere in the D-Cube, the appropriate saved selection would be empty. So if a saved selection pre-exists under the name that would have been used had the item appeared somewhere in the D-Cube, that saved selection is deleted. Saved selection objects can have names with a maximum of 31 characters. The saved selections names created by this macro have the following lengths: Prefix Length + Totals Name Length + Suffix Length + [if CubeName parameter <>0, then CubeName parameter +2, else 0] If the sum of these exceeds 31 for any particular Total, the macro truncates the Total name (beginning at the right) to achieve a saved selection name of 31 characters. If the (absolute size of) CubeName parameter is greater than the actual length of a particular name of one of the D-Cubes in Cubes, that D-Cube name will be inserted in full but not padded. Totals names will still be truncated to 31 - PrefixLen - SuffixLen -CubeName - 2, to ensure that the same truncated Totals names are generated for each of the target D-Cubes in Cubes. This macro can interact with a previously set @AddLocalPreselection macro command. If the dimension addressed by @AddLocalPreselection is different from the dimension addressed by @DCubeCreateDSels, each saved selection created will be reduced on the dimension addressed by @AddLocalPreselection (that is, will be an explicit selection as defined in the @AddLocalPreselection parameter, rather than an empty [implicitly means all] selection). If the dimension addressed by @AddLocalPreselection is the same as the dimension addressed by @DCubeCreateDSels, each saved selection created will, on that dimension, be the intersection of the items defined in the LocalPreselection and the items that would otherwise have been in

User Guide 675

Chapter 13: Macros the saved selection. If the resulting intersection is null, an empty selection is created (implicitly means all items).

@DCubeCreateTSels
This D-Cube macro is used to create one or more saved selections for a specific set of cubes, based on specific subtotals of a D-List that is used by all those cubes.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeCreateTSels in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Cubes row, click Edit ObjectList and then select the D-Cubes. The D-Cubes you select are the Target D-Cubes for which saved selections are to be created. 2. In the Totals row, click Edit DListSelection and then select the D-List items. A selection of items (normally FORMULA items) in a D-List. This D-List must be used by all the cubes specified in the Cubes parameter. A Saved Selection will be created for each item chosen here, for each cube in Cubes. Each Saved Selection will include the respective D-List item and all its children, which means expansion to the maximum possible level as defined by the formula against the item, also applied recursively to children. The Saved Selection Name will in each case be the same as the respective item name, subject to the optional Prefix, Suffix and CubeName parameters. 3. In the Permanent row, click Edit DListSelection and then select the set of text strings. The text strings you select should match exactly the D-List item names of items that are to be included in all saved selections. 4. In the Prefix box, type a prefix. The prefix is an optional text string, attached automatically to the front of every saved selection name, and can be used in conjunction with a suffix. 5. In the Suffix box, type a suffix.

676 Analyst

Chapter 13: Macros The suffix is also an optional text string, attached automatically to the end of every saved selection name, and can be used in conjunction with a prefix. 6. In the CubeName box, enter an integer between -31 and 31 (zero can be used). The integer you enter specifies the number of characters from the front of the respective cube name that also will be used in the saved selection name. The value zero (0) indicates that no characters will be used. A positive value indicates that the respective number of characters, counting from the beginning of the cube name, will be inserted before the Totals name but after the prefix (if any). A negative value indicates that the respective number of characters, counting from the beginning of the cube name, will be inserted after the total name but before the suffix (if any). CubeName characters always are contained in parentheses. For example, (cube name). 7. In the Spacer box, enter a spacer. The spacer is a string (character) used to separate the CubeName part from the Totals part in the resulting Saved Selection Name. 8. Move the macro in the list using the arrows (if necessary). 9. Close the macro. You will be prompted to name and save the macro. Click Yes. 10. Name and save the Macro and click OK.

Additional Notes
The parameters Totals, Data, Cubes, Lists, and Permanent must be edited at least once to set up the macro. The strings in Permanent can be empty, in which case no Permanent items are defined. If creating saved selections for more than one cube, it is necessary to specify a CubeName parameter not equal to zero. If the CubeName parameter is left as zero in such cases, for any particular Total parameter, the saved selections created for each cube will have identical names. The effect of this is, that at the end of the macro, only saved selections will exist for the last cube defined in the Cubes parameter. Hence, it is necessary to differentiate the saved selection names by also including enough of each cube name to ensure uniqueness. This macro automatically overwrites (update) pre-existing saved selections with the new definitions as derived by the macro specification. The unique identification of a saved selection is only the saved selection name. If no items are specifically selected from the D-List in Totals, No Saved Selections will be created. This is an exception to the rule Empty selection equals all. Saved selection objects - like other objects - can have names with a maximum of 31 characters. The saved selections names created by this macro will have the following lengths: Prefix Length + Totals Name Length + Suffix Length + [if CubeName parameter <>0, then CubeName parameter +2, else 0].

User Guide 677

Chapter 13: Macros If the sum of these exceeds 31 for any particular Total, the macro truncates the Total name (beginning at the right) to achieve a saved selection name of 31 characters. If the (absolute size of) CubeName parameter is greater than the actual length of a particular name of one of the cubes in Cubes, that cube name is inserted in full but not padded. Totals names will still be truncated to 31 - PrefixLen - SuffixLen -CubeName - 2 to ensure that the same truncated Totals names are generated for each of the target cubes in Cubes. For this reason, it is advisable not to specify an excessively large CubeName parameter. This macro can interact with a previously set @AddLocalPreselection as follows: If the dimension addressed by @AddLocalPreselection is different from the dimension addressed by @DCubeCreateTSels, each Saved Selection created will be REDUCED on the dimension addressed by @AddLocalPreselection (i.e. will be an explicit selection as defined in the @AddLocalPreselection parameter, rather than an EMPTY [implicitly means ALL] selection). If the dimension addressed by @AddLocalPreselection is the same as the dimension addressed by @DCubeCreateTSels, each Saved Selection created will, on that dimension, be the INTERSECTION ("") of the items in the LocalPreselection and the items that would otherwise have been in the Saved Selection. If the resulting intersection is null, an empty selection is created, and consequently no saved selections will be created.

@DCubeDeleteSels
This D-Cube macro is used to delete one or more existing saved selections for a specific set of cubes.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeDeleteSels in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Cubes row, click Edit ObjectList. Select one or more cubes for which Saved Selections are to be deleted. 2. In the Prefix box, type a prefix. The prefix is an optional text string up to 31 characters long, used as a filter on saved selection names, and can be used in conjunction with a Suffix. For example, a Prefix of "BB" means that selections with names beginning with "BB" are deleted.

678 Analyst

Chapter 13: Macros 3. In the Suffix box, type a suffix. The suffix is an optional text string up to 31 characters long, used as a filter on saved selection names, and can be used in conjunction with a Prefix. For example, a Suffix of "XYZ" means that selections with names beginning with "XYZ" are deleted. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

Additional Notes
If both a Prefix and Suffix are specified, both filters apply Logical AND. This means that only those saved selections are deleted whose names begin with the Prefix and end with the Suffix. The filtering on Prefix and Suffix is case sensitive.

@DCubeDeselect
The @DCubeDeselect macro takes the active open D-Cube selection and reduces the selection by the items chosen. If there is a mismatch between any of the dimensions in @DCubeDeselect and those of the active open D-Cube, a message warns you, but will still attempt to deselect the items chosen. @DCubeDeselect also lets you change the orientation of the open selection.

Split
The selection of items from a D-Cube to exclude from the currently open active D-Cube. If you choose an empty selection, it will not deselect any items on that dimension. Click Slice to change the orientation of rows and columns. Option: Y or N or leave blank. This sets the default answer to any system prompts, which would typically prompt you to save the cube if you could lose any data by reducing the open selection. If you leave the option blank, you will receive the normal prompts and will have to provide an answer at runtime. Note: The data can be lost when reducing an open selection if you set N as the option.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list.

User Guide 679

Chapter 13: Macros 2. Click DCubeDeselect in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select a D-Cube in the Select or Create New D-Cube dialog box, and then click OK. You must select the same D-Cube as the current active D-Cube for this macro to run. 3. Make a selection of the D-Cube, and then click OK. 4. In the Option line, enter Y or N, or leave it empty. 5. If empty, the user will be prompted with the prompts that the system would normally ask during the execution of this operation. If Y or N, and then yes or no will be used as the response buttons to all prompts. 6. Click Finish. 7. Move the macro in the list using the arrows (if necessary). 8. Close the macro. You will be prompted to name and save the macro. Click Yes. 9. Name and save the Macro and click OK.

@DCubeExport
@DCubeExport (Filename; Selection; Options) The DCubeExport macro is used to export data from a D-Cube to a text file (ASCII file) or to the clipboard. It is recommended that you record this macro initially then amend the parameters if required.

Parameters Filename
The pathname of the export file. You can use the full pathname or you can use the {LIB} parameter. At run-time, the {LIB} parameter is replaced by the current path of the library that contains the D-Cube. For example {LIB}\export.csv exports to a file named export.csv in the current library. <Clipboard> means export to the Windows clipboard.

Selection
The selection of cells to export. The default setting is to export the current selection, with the current orientation of rows, columns, and pages including any zero suppression of totals and details set in the current view.

680 Analyst

Chapter 13: Macros

Options
A series of options that define the format of the export. If you are creating this command from the Macro editor screens the Options list will be blank. It is advisable to record this macro and then amend the options as required. Clipboard=No or Yes No means export to ASCII or flat text files. Yes means export to the clipboard.

Separator=CSV, TAB, ALG or SSV Defines the separator between columns of data or between the dimensions. This can be a comma (CSV), Tab (TAB), aligned columns with a space between columns (ALG) or a semi-colon (SSV) .

Single=Yes or No Yes means exports the data as a single column. No means export the data in multi-column format, using the last dimension as the data dimension.

Regional=Yes or No Yes means unless another specific format has been applied, respect the regional settings for the numeric formats as defined in control panel. For example, in continental Europe, this would be a full-stop for the thousands separator, a comma for the decimal separator. In the UK and USA, it would mean a comma for the thousand separator, a full-stop for the decimal separator. No will use the UK and USA format for all items where no specific format has been applied.

CHeadings=Normal, Top, EachPage, None Normal is the default behavior. In multi-column view, it puts column headings above each page, but does not show the D-List names for the row and page dimensions. In single column view, Normal means that no column headers are shown. Top puts the D-List names and column headers at the top only. Each Page puts the dimension names and the column headers above each page of the export. In single-column exports, the concept of pages is meaningless, so it only puts the dimension names at the top. None does not enter column headings at all.

WriteMode=Overwrite or Append:
Overwrite will overwrite an existing file of the same name, though it will prompt you before you replace the old file. Append adds the exported data onto the bottom of the existing file if you export to a file that already exists.

User Guide 681

Chapter 13: Macros Default=Yes or No The default answer to prompts when you run the macro. For example: Default=Yes, when used in conjunction with Overwrite, will answer Yes when asked if you want to replace an old existing file. PipesAsSpaces=Yes Yes means that the pipe symbol will automatically be replaced by a space throughout the entire export file. The pipe symbol | is used in Analyst to indicate a new line for column headings, so is not necessarily wanted when exporting column headers.

NoNumericFormat=Yes or No Yes means export in plain number format without any thousand separator, a minus sign for negative numbers and formatted to as many decimal places as needed (up to 16). The decimal separator will be a full-stop unless the regional settings option indicates otherwise. No means use the numeric formats as displayed in the D-Cube.

Title=any text Displays a heading or title of your choice at the very top of the export file.

Footnote=any text Displays a footnote of your choice at the very bottom of the export file.

HideZero=Rows, Columns or Pages Zero suppression of totals and details are taken from the current view. Zero suppression is dimension specific. Zero suppression of page dimensions requires Suppress Zero Pages to be checked. It is not sufficient to just put the zero suppression on the dimension.

HideTotals=[1]MyLibrary.MyDlist Hides all totals on the chosen D-List. The number in brackets [1] must be increased for each dimension you want to hide. For example: HideTotals=[1]MyLibrary.MyDlistA HideTotals=[2]MyLibrary.MyDlistB HideTotals=[3]MyLibrary.MyDlistC

HideDetails=[1]MyLibrary.MyDlist Hides all details on the chosen D-List. The number in brackets [1] must be increased for each dimension you want to hide. For example: HideDetails=[1]MyLibrary.MyDlistA HideDetails=[2]MyLibrary.MyDlistB HideDetails=[3]MyLibrary.MyDlistC

DimOrder=Yes 682 Analyst

Chapter 13: Macros Yes means export in the underlying dimension order irrespective of the current orientation.

TextQualifier=none, single or double

To apply single or double quotes around text or D-List formatted items. The default is none (to have no text qualifier).

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeExport in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the FileName text box, enter the path of the file to which you will export. 2. Select a D-Cube in the Select or Create New D-Cube dialog box, and then click OK. 3. Click Edit List. In the List Editor dialog box, enter items. Click OK. 4. Click Finish. 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@DCubeIncreaseSelect
The@DCubeIncreaseSelect macro increases the selection of items in the current active view of a D-Cube and also allows you to change the orientation of the D-Cube.

Parameters Split
The selection of additional items to include in the currently open active D-Cube view. If you choose an empty selection, it will not increase the selection of items on that dimension. Click Slice to change the orientation of rows and columns. Position: Top, Bottom or DListOrder: Positions the new items. It will not re-order items in the existing selection.

User Guide 683

Chapter 13: Macros Option: Y or N or leave blank. This sets the default answer to any system prompts.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeIncreaseSelect in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select the current active D-Cube in the Select or Create New D-Cube dialog box, and then click OK. 3. Make a selection of the D-Cube, and then click OK. 4. Select Top, Bottom or DListOrder from the Position drop down box. 5. In the Option line, enter Y or N, or leave it empty. 6. If empty, the user will be prompted with the prompts that the system would normally ask during the execution of this operation. If Y or N, and then yes or no will be used as the response buttons to all prompts. 7. Click Finish. 8. Move the macro in the list using the arrows (if necessary). 9. Close the macro. You will be prompted to name and save the macro. Click Yes. 10. Name and save the Macro and click OK.

@DCubeInput
This D-Cube macro inputs data into the active D-Cube. It is strongly recommended to record this macro to ensure that the correct cell is identified within the macro.

Parameters Input
Any data or command which you can enter manually can be entered here, for example 2500 or grow100.

684 Analyst

Chapter 13: Macros 'Cell' must identify a visible cell in the current slice (visible cells may be less than all the cells in the current slice due to active formatting options).

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeInput in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter the data or command to be input into the appropriate cell in the Input box. 2. Click Edit List. 3. Type the D-List item names identifying the cell on separate lines in the List Editor dialog box. The items names must include1 item from each D-List in the D-Cube and must be typed in the same order as the D-Lists occur in the D-Cube. 4. Click OK. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Click Close, and then name and save the macro.

@DCubeNew
This D-Cube macro creates a new D-Cube using the specified D-Lists.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeNew in the Function list.

User Guide 685

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCube, and select the Target library. 2. Enter the name of the new D-Cube and click OK. 3. Click Edit ListOfDLists. 4. Select the D-Lists to comprise your D-Cube in the Select objects window, and then click OK. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

@DCubeOpen
This D-Cube macro opens a D-Cube using the specified dimensions.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeOpen in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select a D-Cube in the Select or Create New D-Cube dialog box, and then click OK. 3. Select part of the D-Cube by clicking on the Slice button. Verify that the orientation is correct and then click OK. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

686 Analyst

Chapter 13: Macros

@DCubeOpenChooseSel
This D-Cube macro is used to open a D-Cube, prompting the user to choose from a list of saved selections. The list of saved selections from which the user can choose always includes, at the top of the list, the complete D-Cube.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeOpenChooseSel in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCube. 2. Select the D-Cube to be opened and click OK. 3. In the Prefix box, type a prefix. This is an optional string parameter used to filter the Saved Selections. When the macro is run only those saved selections on the D-Cube will be shown, with names that begin with the prefix. The Prefix parameter is case-sensitive. For example a Prefix parameter of "BB" means the saved selection "BB my cube" would be shown. 4. Click Finish and if necessary move the macro in the list using the arrows (if necessary). 5. Close the macro. You are prompted to name and save the macro. Click Yes. 6. Name and save the macro and click OK.

Additional Notes
This macro can be preceded by the macro command @AddLocalPreselection. In this case the selection actually opened will be overridden in the dimension controlled by @AddLocalPreselection. @AddLocalPreselection always takes priority. This applies even to the virtual selection "< Full>". The combination of the macros @AddLocalPreselection and @DCubeOpenChooseSel allows the user to reduce the selection of the D-Cube opened on more than one D-List.

User Guide 687

Chapter 13: Macros

@DCubeOpenNamedSel
This D-Cube macro is used to open a D-Cube using a specific named saved selection.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeOpenNamedSel in the Function list. 3. Click Next.

Macro Wizard Step 2

1. In the Selection row, click Edit Object. Here you select the saved selection to be opened. Click OK. 2. Click Finish. 3. Move the macro in the list using the arrows (if necessary). 4. Close the macro. You will be prompted to name and save the macro. Click Yes. 5. Name and save the Macro and click OK.

Additional Notes
Saved selections are a special case in the object referencing system, in that it is possible to delete a specific saved selection, even if there is any macro which refers to the saved selection being deleted. If the named saved selection does not exist at run time, the macro will fail with an error message "Cannot find Selection <name>". Because it is possible that a macro command of type @DCubeOpenSelection (<specific named selection>) exists while the <specific named selection> to which it refers does not, problems may arise in such cases when moving/copying models from one library to another. Copy will still function correctly if the From switch is set instead of the Between switch. Move will only function correctly, if the <specific named selection> exists at Move time. This macro can be used in conjunction (that is, preceded by) a command of type @AddLocalPreselection, in which case the Selection actually opened will be overridden in the dimension controlled by @AddLocalPreselection (normally NOT the same dimension as that against which the Selections were originally generated). @AddLocalPreselection always takes priority.

688 Analyst

Chapter 13: Macros

@DCubeOpenSelect
This D-Cube macro opens a D-Cube, allowing the user to override the selection on the dimensions identified in the Override parameter.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeOpenSelect in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select a D-Cube in the Select or Create New D-Cube dialog box, and then click OK. The D-List (s) selected must be used in the target D-Cube otherwise the macro will not work. 3. Make a selection of the D-Cube, and then click OK. 4. Click Edit ListOfDLists. 5. Select the D-Lists to override your D-Cube in the Select objects window, and then click OK. 6. Click Finish. 7. Move the macro in the list using the arrows (if necessary). 8. Close the macro. You will be prompted to name and save the macro. Click Yes. 9. Name and save the Macro and click OK.

@DCubePage
This D-Cube macro switches to the specified page in a specified dimension. The D-Cube must be open when this macro is run and the page dimension of a D-Cube is not a column or a row. It is recommended that this macro is recorded and then edited if required.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

User Guide 689

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubePage in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DList. 2. Select the D-List that comprises the pages of the open D-Cube, and then click OK. 3. Type in an item name from the D-List specified in the previous step. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

@DCubePageId
This D-Cube macro is similar to the @DCubePage macro, but instead stores the ID of the selected dimension item rather than the name, thereby requiring less maintenance when items are renamed.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubePageId in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DListSelection. 2. Select an item to jump to on a D-List, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary).

690 Analyst

Chapter 13: Macros 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@DCubePrint
This D-Cube macro prints the contents of an open D-Cube. It is recommended that you record this macro initially then amend the parameters if required.

Selection
The selection of cells to print. The default setting is to print the current selection, with the current orientation of rows, columns, and pages including any zero suppression of totals and details set in the current view.

Options
If you are creating this command from the Macro editor screens the Options list will be blank. It is therefore advisable to first record this macro and then amend the options as required.

PrinterName="PrinterName"
The name of the printer (or blank if only 1 printer is installed).

Orientation=Portrait or Landscape
Select the page orientation.

PrintAnnoFlag=Yes or No
Enter Yes to print annotations at the bottom of each page or No

PrintFont="FontName"
Enter Font Name (e.g. Arial Narrow)

FontSize=9
Enter Font size

FixedWidth=15
Enter column width if a fixed width column is required

TopMargin=72.00 pt
Enter top margin size in pts (e.g. 72.00 pt)

BottomMargin=72.00 pt
Enter top margin size in pts (e.g. 72.00 pt)

User Guide 691

Chapter 13: Macros

LeftMargin=54.14 pt
Enter left margin size in pts (e.g. 54.14 pt)

RightMargin=54.14 pt
Enter right margin size in pts (e.g. 54.14 pt)

HeaderMargin=36.00 pt
Enter header margin size in pts (e.g. 36.00 pt)

FooterMargin=36.00 pt
Enter footer margin size in pts (e.g. 36.00 pt)

Header=text
Enter header text. The following system variables can be included in the text {TODAY}, {PAGENO} , {FILE_NAME) and {FILE_DESCRIPTION}.

LFootnote=text
Enter left footnote text. The following system variables can be included in the text {TODAY}, {PAGENO}, {FILE_NAME) and {FILE_DESCRIPTION}.

RFootnote=text
Enter right footnote text. The following system variables can be included in the text {TODAY}, {PAGENO}, {FILE_NAME) and {FILE_DESCRIPTION}.

TopRule=Yes or No
Enter Yes to include a top rule

BottomRule=Yes or No
Enter Yes to include a bottom rule

HideZero=Rows, Columns or Pages

Zero suppression of totals and details are taken from the current view. Zero suppression is dimension specific. Zero suppression of page dimensions requires Suppress Zero Pages to be checked. It is not sufficient to just put the zero suppression on the dimension.

HideTotals=[1]MyLibrary.MyDlist
Hides all totals on the chosen D-List. The number in brackets [1] must be increased for each dimension you want to hide. For example: HideTotals=[1]MyLibrary.MyDlistA

692 Analyst

Chapter 13: Macros HideTotals=[2]MyLibrary.MyDlistB HideTotals=[3]MyLibrary.MyDlistC

HideDetails=[1]MyLibrary.MyDlist
Hides all details on the chosen D-List. The number in brackets [1] must be increased for each dimension you want to hide. For example: HideDetails=[1]MyLibrary.MyDlistA HideDetails=[2]MyLibrary.MyDlistB HideDetails=[3]MyLibrary.MyDlistC

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubePrint in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select a D-Cube in the Select or Create New D-Cube dialog box, and then click OK. 3. Make a selection of the D-Cube, and then click OK. 4. Click Edit List in the List Editor dialog box and enter items. Click OK. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

@DCubeReselect
This D-Cube macro reselects the current view of the active D-Cube. The parameter, Option, can be empty, Y or N. If empty, the user will be prompted with the prompts that the system would

User Guide 693

Chapter 13: Macros normally ask during the execution of this operation. If Y or N, then yes or no will be used as the response buttons to all prompts.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeReselect in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCubeSelection. 2. Select a D-Cube in the D-Cube Select or Create New dialog box, and then click OK. Note: If you inserted the @DCubeOpen macro before the @DCubeReselect macro, you must select the same D-Cube for this macro to run. 3. Make a selection of the D-Cube, and then click OK. 4. In the Option line, enter Y or N, or leave it empty. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

@DCubeSort
This D-Cube macro automates the D-Cube sort functions, including what D-Cube to sort, what dimension to sort, the item on the dimension to use as the base for sorting, and whether to sort by ascending or descending mode. The macro works on an open or closed D-Cube, but if an open D-Cube is used, the changes made to the sort information must be saved in a separate macro step.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

694 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeSort in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCube. Select the D-Cube to sort. 2. Click Edit DList. Select the dimension (D-List) to sort. 3. Click Edit DListSelection. Select an item on the dimension to use as a base for sorting. If you want to fully define the sort, you can specify an item on each of the other dimensions in the cube, apart from the dimension you are about to sort. Subsequent calls to this macro step will only add info to the existing sort specifications for the cube, which lets you to keep adding further steps until the sort is fully specified on all dimensions. The system will use defaults for the dimensions where nothing is specified. 4. Select Ascending or Descending mode. 5. Select the Clear check box to clear any existing sort specifications, allowing you start a new sort. 6. Click Finish. 7. Move the macro in the list using the arrows (if necessary). 8. Close the macro. You will be prompted to name and save the macro. Click Yes. Name and save the Macro and click OK.

@DCubeTranspose
This D-Cube macro transposes the rows and columns in the current view of the active D-Cube. No parameters are required for this command.

To use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeTranspose in the Function list.

User Guide 695

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click Finish. 2. Move the macro in the list using the arrows (if necessary). 3. Close the macro. You will be prompted to name and save the macro. Click Yes. 4. Name and save the Macro and click OK.

@DCubeUpdate
@DCubeUpdate runs the update links list for one D-Cube. The D-Cube to update is identified by the macro's only parameter: DCube. You can only use the @DCubeUpdate command to update a D-Cube that has an update list defined. When you want to run D-Cube update links in a macro, you have two choices: You can write a macro consisting of a series of @DCubeUpdate commands, or you can write (or record) a macro which opens each D-Cube before running the update links. The first type of macro will be simpler to create and edit (it consists of fewer commands), but the second type of macro may run faster: each D-Cube updated will be opened, saved and closed only once. If you want the update links to only update a selection of the target cube then the @DCubeUpdate command must be preceded by one of the D-Cube open commands which only opens the required selection.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click DCubeUpdate in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit DCube. 2. Select a D-Cube, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes.

696 Analyst

Chapter 13: Macros 6. The Save Macro As dialog box appears. Name and save the Macro and click OK.

@GenerateTransformerModel
The @GenerateTransformerModel macro automates the steps you perform in the Generate Transformer Model wizard. Use the Generate Transformer Model wizard to generate a Cognos Transformer Model from a table-only database layout and create Cognos PowerCube(s). You can publish secured or unsecured PowerCube(s) to a Business Intelligence package in Cognos Connection and view its content using any of the Cognos 8 studios. You can also view unsecured PowerCubes with PowerPlay Series 7. With the Generate Transformer Model, you can: generate a Transformer model generate a Transformer model and a PowerCube create a PowerCube from an existing Transformer model

Note: Before creating the @GenerateTransformerModel macro, you need to perform a table-only publish.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click GenerateTransformerModel in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit TransformerModelSpec. 2. Complete the Generate Transformer Model wizard to edit the @GenerateTransformerModel macro parameters. When you complete the wizard, all of the parameters will be stored in the @GenerateTransformerModel macro. 3. Move the macro in the list using the arrows (if necessary). 4. Close the macro. You will be prompted to name and save the macro. Click Yes. 5. The Save Macro As dialog box appears. Name and save the Macro and click OK.

User Guide 697

Chapter 13: Macros

@Publish
Publishing from Analyst is performed through a wizard that takes the user through the steps of selecting the library and cubes to be published, providing data filtering parameters and specifying the target database as well as its connection parameters. The @Publish macro automates the publish process, including which D-Cubes to publish, source and target dimensions to publish, and what datastore to use.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click Publish in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit CubesAndDimensions. 2. Click Select to choose the D-Cubes you want for publish. 3. Click the required D-Cubes and move them to the bottom pane. Click OK. 4. Click Dimension for publish for each D-Cube and from the drop-down menu, click a dimension. This is a correspondence between each D-Cube you have selected and what dimension to use for publish in this D-Cube. Click OK. 5. Click Edit DataStore. Select the database options you want to use. See Analyst Publish for more information on the database options. 6. Click Edit PublishOptions to specify Table-only layout or View layout, and Common Options. 7. Select the Include zero or blank values check box to include empty or zero data. 8. Select the Include Annotations check box to publish annotations. 9. Select the Overwrite check box to overwrite existing data. 10. Click Finish. 11. Move the macro in the list using the arrows (if necessary). 12. Close the macro. You will be prompted to name and save the macro. Click Yes. 13. The Save Macro As dialog box appears. Name and save the Macro and click OK.

698 Analyst

Chapter 13: Macros

@SliceCommand
@SliceCommand(Lists; Lookup; Criteria), and @Command The @SliceCommand macro lets you apply a D-Cube command to a slice of a model. The @SliceCommand modifies the behavior of the @Command macro by restricting the D-Cube command to a selection of items from a D-List. This selection of items from a shared D-List is known as a slice. @SliceCommand only works in conjunction with the @Command macro and must precede the @Command step in the macro. The slice is defined in a simple table. The @Command macro is a macro that applies a D-Cube command to an entire D-Cube. It can be used to zero a model or apply locks, hold, protects, or indeed any other D-Cube command. The @Command operation will open the D-Cube, apply the command, then save and close the D-Cube without any further prompts.

Parameters Lists
The D-Lists on which to do the selection. Usually this is just the D-List used as rows in the look-up table. However you can select any number of similar D-Lists. The selection will be those D-List Items that match the descriptions of items in the D-List in the look-up table.

Lookup
The table that defines the selection to which the command is applied. This is a two-dimensional D-Cube that has the D-List you want to slice on as rows, the criteria as columns. When selecting the Lookup parameter, first select a D-Cube, then make a selection from the D-Cube that has an empty selection for the D-List you are going to slice, and has a single item selected from each of the other dimensions. Note that you are not selecting the items to include in the slice. All you are doing is opening a two-dimensional table. The orientation of rows and columns is important.

Criteria
The criteria on what to include in the selection. This is another selection from a D-List that is used as the D-List format in the look-up table.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click SliceCommand in the Function list.

User Guide 699

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2 for @SliceCommand

1. Click the Edit ListOfDLists button to select the D-Lists whose items should be matched to create the selections. Click OK. 2. Click the Edit DCubeSelection button to select the data to use as a driver. This should be a single page, single column D-Cube selection Click OK. 3. Click the Edit DListSelection button to select the items to be included in the selection. 4. Click OK. 5. Click Finish. 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

@SliceUpdate
@SliceUpdate(Lists; Lookup; Criteria). The @SliceUpdate macro lets you update a model or cube by slice. It can be used to update both Analyst and Contributor cubes and will work with Analyst-Analyst; Analyst-Contributor; Contributor-Contributor and Contributor-Analyst links. Its purpose is to improve volumes, maintenance, and robustness of update macros. By updating a slice at a time, you can therefore work with much larger data volumes allowing Contributor and very large Analyst cubes to be updated. It can also be used to allow the user to determine which slices of the target cube(s) are updated. When the target of the link is an Analyst cube, SliceUpdate must be followed by an @DCubeUpdate command, it will not work on @DLinkExecute. When the target is a Contributor application, then @SliceUpdate should be followed by @DLinkExecute or @DlinkExecuteList. @SliceUpdate modifies the behavior of @DLinkExecute and @DCubeUpdate macros by restricting the update or D-Link execution to a selection of items from a D-List. This selection of items is known as a slice. When Contributor is the target of the link, it is only possible to slice on the e-list. @SliceUpdate works in conjunction with the @DLinkExecute and @DCubeUpdate macros and must precede either of these commands in the macro to be effective. Each @SliceUpdate specifies items from a single or similar D-Lists. To specify items from different D-Lists then multiple @SliceUpdate commands are required each controlling different D-Lists. The slice to be updated is controlled from a look up D-Cube containing slice control data.

Parameters
Only 3 parameters are required to define this macro.

700 Analyst

Chapter 13: Macros

Lists
The D-Lists on which to base the slice update. Usually this is the D-List used as rows in the lookup table. However you can select any number of similar D-Lists. The selection will be those D-List Items that match the descriptions of valid items in the D-List in the lookup D-Cube. If you are updating a Contributor model then the D-List will one containing the e list item ID's.

Lookup
The lookup D-Cube defines the selection to be updated. This should be a single page, single column selection within a D-Cube The D-Cube has the D-List you want to slice on as rows, and the criteria as columns.

Criteria
The criteria on what to include in the selection. This is selection from a D-List that is used as the D-List format in the lookup D-Cube. More than one item can be chosen which will allow larger slices of the Target D-Cubes to be updated. Examples include The item Yes from a D-List containing the items Yes and No. This would update all items which had a Yes flag shown against them in the lookup cube. The item Current Slice from a D-List containing a list of slice numbers (e.g. Current Slice, Slice+1, Slice+2, Slice+3 etc.). This would update all the items which had Current Slice as an attribute in the lookup D-Cube. The items Jan, Feb, Mar from a Periods D List. This would update those items which were shown to have a flag of either Jan, Feb or Mar in the lookup cube.

The @SliceUpdate remains in force until a second @SliceUpdate macro referring to the same D-List is used or the macro completes (including any sub macros). When another @SliceUpdate macro is encountered, the restriction gets applied to subsequent steps. If two @SliceUpdate steps refer to different D-lists, the selection becomes the intersection of the two lists where they are encountered in a D-Cube. If a @DCubeUpdate step is encountered that does not have any of the D-lists in the Lists parameter in @SliceUpdate, the full D-Cube is updated. A preceding D-Cube Open step will modify the selection. It will be the intersection of the open selection and the selection defined in the @SliceUpdate.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click D-Cube in the Group list. 2. Click SliceUpdate in the Function list.

User Guide 701

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click the Edit ListOfDLists button to select the D-List(s) whose items should be matched to create the selections and click OK. 2. If multiple D-Lists are selected, each Target D-Cube(s) (i.e. those being the target of the subsequent @DLinkExecute or @DCubeUpdate commands) should not use more than one of these lists. 3. Lookup. Click the Edit DCubeSelection button to select the D-Cube which defines which slice is to be updated and click OK. When selecting the Lookup parameter, make a selection from the D-Cube to show a single page, single column of data. The D-Cube has the D-List you want to slice on as rows as an open selection, and the criteria as columns. Notice that you are not selecting the items to include in the slice. Click on the slice button to ensure that the orientation of rows and columns is correct. 4. Criteria. Click the Edit DListSelection button to select the items which define the criteria to be used and click OK. Those items in the Lists which meet the Criteria in the lookup D-Cube will be included in the subsequent @DCubeUpdate or @DLinkExecute commands. 5. Click Finish.

Example of @SliceUpdate to Increase Volume Limits

In order to update a model or cube in steps, one slice at a time, you can use the @SliceUpdate macro in combination with the @TestData macro to create a looping macro which will update the target Contributor or Analyst cube(s) in q number of sequential steps. The practical effect of this is a dramatic increase in the volumes that can be updated before you reach the limit imposed by the memory limits of your computer. Two macros are required: Control macro Looping macro.

A D-Cube controls which slice is currently being used in the lookup definition of the @SliceUpdate macro. The lookup D-Cube should use the D-List on which you want to base the slice update (see Lists definition above) and an Attributes D-List which has 2 items - Specify Step and Current Step. In the example below the Versions D-List is the basis for the slice update. The Lookup D-Cube will initially look as follows:

Lookup Cube
Specify Step Current Step

702 Analyst

Chapter 13: Macros

Lookup Cube
Budget V1 Budget V2 Q2 Forecast Q3 Forecast Current Step Step+1 Step+2 Step+3

Both the items Specify Step and Current Step are formatted on a D List which contains the following items:

Steps D-List
Description Current Step Step+1 Step+2 Step+3 IID 1 2 3 4

It is important that all the IID's of all items in this D-List are sequential.

Control Macro
This executes an internal D-Link then runs the looping macro @DLinkExecute(Which Step Internal).This copies all the values from the item Specify Step to the item Current Step. At this point the lookup cube looks as follows:

Lookup Cube
Specify Step Budget V1 Budget V2 Q2 Forecast Q3 Forecast Current Step Step+1 Step+2 Step+3 Current Step Current Step Step+1 Step+2 Step+3 User Guide 703

Chapter 13: Macros

@MacroExecute (Looping Macro)

This macro updates the cubes for the current slice, then opens the Lookup cube and subtracts 1 from all the values against the Current Step item, and saves and closes the cube. It then checks to see if any Versions are flagged as Current Version in the lookup D-Cube, if so it restarts the looping macro, if not it exits from the looping macro back to the control macro which is then complete. The macro command lines will look like the following: @SliceUpdate(Versions; Lookup Cube; Stepd D-List) @DCubeUpdate or @DLinkExecute (these will update either Analyst D-Cubes (using the update table) or a Contributor cube (using @DLinkExecute) @DCubeOpen(Lookup Cube) @DCubeCommand(subtract1; Selection from Lookup Cube). This subtracts 1 from the Current Step item Close(y) @TestData(Selection from Lookup Cube; "ALL <=0"; ; "&Restart") The looping macro works as follows: In the first iteration, just the slice Budget v1 is updated and 1 is subtracted from the current Step item in the lookup cube. The lookup cube then looks like this:

Lookup Cube
Specify Step Budget V1 Budget V2 Q2 Forecast Q3 Forecast Current Step Step+1 Step+2 Step+3 Current Step Step+1 Step+2 Current Step

At the end of each iteration, the Current Step item is tested to see if it is all zero (using @TestData macro). If it is all zero, the macro finishes, if not the macro restarts and this time updates the slice Budget V2. This process continues until all the versions have been updated.

File Map Macros

File map macros deal with macro functions relating to file maps. Beside each macro is an indicator showing whether you need to have opened the object the macro refers to. If it requires an active object but can not find one, the macro will not work.

704 Analyst

Chapter 13: Macros

Macro name
@FMapNew @FMapOpen

Requires Active Object

No No

@FMapNew
This file map macro creates a new file map. No parameters are required in this command.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click FMap in the Group list. 2. Click FMapNew in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Finish. 2. Move the macro in the list using the arrows (if necessary). 3. Close the macro. You will be prompted to name and save the macro. Click Yes. 4. Name and save the Macro and click OK. Note: When you run this macro, you will have to define the file to be mapped.

@FMapOpen
This file map macro opens the specified file map.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click FMap in the Group list. 2. Click FMapOpen in the Function list.

User Guide 705

Chapter 13: Macros 3. Click Next.

Macro Wizard Step 2

1. Click Edit FMap. 2. Select a file map in the Select or Create New File Map dialog box, and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

A-Table Macros
A-Table macros deal with macro functions relating to saved allocation tables. Beside each macro is an indicator showing whether you need to have opened the object the macro refers to. If it requires an active object but can not find one, the macro will not work.

Macro name
@ATabOpen @ATabRefresh @ATabImportCognosPackage @ATabImportDelimitedText @ATabImportFileMap @ATabImportOdbc

Requires Active Object

No Yes No No No No

@ATabOpen
This A-Table macro opens a specified A-Table.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

706 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabOpen in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ATable. 2. Select an A-Table and Library in the Select or Create New A-Table dialog box and then click OK. 3. Click Finish. 4. Move the macro in the list using the arrows (if necessary). 5. Close the macro. You will be prompted to name and save the macro. Click Yes. 6. Name and save the Macro and click OK.

@ATabRefresh
Refreshes either the source or target side of an A-Table where it is linked to an mapped ASCII file. The A-Table must be open to run this command. This command only updates the source or target items and does not amend or create allocation table relationships in the central columns.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabRefresh in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Enter either Source or Target to identify which side of the A-Table is to be refreshed. 2. Click Edit FMap and select a filemap from which the A-Table should be refreshed. 3. Enter the name of the column to use from the appropriate File Map. User Guide 707

Chapter 13: Macros 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes. 7. Name and save the Macro and click OK.

@ATabImportCognosPackage
Automates the importing of items in a published Cognos Package to an A-Table.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabImportCognosPackage in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ATable. Select an A-Table and Library in the Select A-Table dialog box and then click OK. 2. Click EditAtabPackageDataMap. You need to select the Cognos package data and tell it how to map the columns to the attributes. 3. Click Select, then choose a package from the drop box. 4. Select a Query Subject. 5. Under the Available Query Items in selected Query Subject list, select the available Query Items in the Query Subject and move them to the Selected Query Items pane. 6. Select the Display preview of selected query items check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. 7. Click OK. 8. In the Specify import data screen, you can specify how to map the columns to the attributes. Select an attribute from the drop down menu, for example Skip, Source side, Target side, Signs - and then click OK. 9. Click Finish. 10. Save and name your macro before closing. 708 Analyst

Chapter 13: Macros 11. Click OK. 12. Click Finish. 13. Move the macro in the list using the arrows (if necessary). 14. Close the macro. You will be prompted to name and save the macro. Click Yes. 15. Name and save the Macro and click OK.

@ATabImportDelimitedText
Automates the refreshing of an A-Table from delimited ASCII files.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabImportDelimitedText in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ATable. Select an A-Table and Library in the Select A-Table dialog box and then click OK. 2. Click EditAtabTextDataMap. Select a text file and specify a delimiter to use as a separator. Click the drop-down arrow to change the table mapping of columns to attributes of the allocation table. The key words to map columns to in this table are Source, Target and Signs. Signs is optional. If you specify a column to contain signs, the system will look at the first character of each record in this column, and any records that start with a "-" will be interpreted as a sign switch in the allocation table, and any other character will be interpreted as no sign switch. If signs is specified in the allocation table, data may switch signs when going through that A-Table. You must mark columns for both target side and source side before you can import text.

3. Click OK. 4. Click Finish. 5. Move the macro in the list using the arrows (if necessary). 6. Close the macro. You will be prompted to name and save the macro. Click Yes.

User Guide 709

Chapter 13: Macros 7. Name and save the Macro and click OK.

@ATabImportFileMap
Automates the refreshing of an A-Table from a File Map.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro. 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabImportFileMap in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ATable. 2. Select an A-Table and Library in the Select or Create New A-Table dialog box and then click OK. 3. Click FileMap. Select a library and FileMap from which to import. 4. Click Edit Table. Select or change the table mapping of column numbers to attributes of an object. The key words to map column numbers to in this table are Source, Target, or Signs. Signs is optional. Only these three key words are recognized in the target side of the table. The Source side of the table contains the column numbers of the target data. Choose signs in a third column to contain the signs for the A-Table if data should switch signs when going through that A-Table. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

@ATabImportOdbc
Automates the refreshing of an A-Table from an ODBC source.

Steps to use this macro

1. From the Tools menu, click Macros, New Macro.

710 Analyst

Chapter 13: Macros 2. Click Insert.

Macro Wizard Step 1

1. Click A-Table in the Group list. 2. Click ATabImportOdbc in the Function list. 3. Click Next.

Macro Wizard Step 2

1. Click Edit ATable. 2. Select an A-Table and Library in the Select or Create New A-Table dialog box and then click OK. 3. Click Edit OdbcData. Select an ODBC source. Enter a user ID and password. Select or clear Keep connection open check box. Enter the driver options. Click Connect.

4. Click Edit Table. Select or change the table mapping of column numbers to attributes of an object. The key words to map column numbers to in this table are Source, Target, or Signs. Signs is optional. Only these three key words are recognized in the target side of the table. The Source side of the table contains the column numbers of the target data. Choose signs in a third column to contain the signs for the A-Table if data should switch signs when going through that A-Table. 5. Click Finish. 6. Move the macro in the list using the arrows (if necessary). 7. Close the macro. You will be prompted to name and save the macro. Click Yes. 8. Name and save the Macro and click OK.

User Guide 711

Chapter 13: Macros

712 Analyst

Chapter 14: A-Tables (Allocation Tables)

An A-Table is an allocation table that shows how two lists correspond. It is useful for transferring data when there is no character match possible between lists of items. You can use an A-Table in a D-Link to import data from another program or to copy data between D-Cubes. In an A-Table, the correspondence between items can be one to one, many to one, one to many or many to many.

Example
You might maintain an employees D-List which has sub-totals according to the geographical location of the employees. However, for certain parts of the budget you might wish to correspond employees with the department in which they work. Your a-Table might then appear as follows: Employee B Employee C Employee D Employee E Administration Sales Sales Marketing

When you want to pair two D-Lists in a D-Link using allocation, you have three choices: You can use a local allocation table ((p. 242)). You can load a saved A-Table. You can use a selection from an allocation D-Cube.

Generally, the type of allocation table used in a D-Link makes no difference to the way the D-Link runs. Frequently, you will create multiple D-Links which use the same allocation table - for example, when consolidating data from multiple source D-Cubes with a similar structure into one target D-Cube. You can load a saved A-Table into any number of D-Links belonging to any number of users. D-Links will always use the current version of the A-Table when they are run, so by maintaining one A-Table you can automatically maintain the allocation performed by all D-Links which use the A-Table. You can also use a large A-Table in a D-Link, even if only a subset of the source and/or target items are found in that D-Link. You may also use a saved A-Table simply to take advantage of the extra facilities it offers - for example, sign changing per line, highlighting of unassigned items, and so on. You can create a new allocation table from scratch, or save a local allocation table in a D-Link as an A-Table.

User Guide 713

Chapter 14: A-Tables (Allocation Tables) A-Tables are most frequently used to perform allocations in a D-Link, but you can also use an A-Table in a Map to translate text data. For information about importing text and date data, see "General Steps to Import Data into an A-Table" (p. 717).

Creating an A-Table
Create an A-Table to transfer data when there is no character match possible between lists of items, in a D-Link to import data from another program, or to copy data between D-Cubes. Steps From the File menu, click New, A-Table. Select a source and target for the A-Table (p. 714) or import data into an A-Table (p. 717). Create the allocation table entries, (p. 719). Name and save the A-Table. Before you close the new A-Table, you can give it a description and attach notes to it by clicking the File menu, and then clicking Summary Info. Any description entered here will be shown at the bottom of the Select A-Table dialog box when opening an A-Table. Note that if the A-Table uses a linked D-List as its source and/or target, the Objects used tab in the Summary information dialog box will give you the name of the D-Lists used in the A-Table.

Selecting Source and Target for an A-Table

Select a source and target for the A-Table by choosing to use a D-List, D-List from a D-Cube, a mapped ASCII File, a delimited ASCII file, an ODBC (SQL) database, data from Cognos Finance, or a Cognos package. Using a mapped ASCII file is the source preferred method because this option allows you to refresh the import of dimension items. Mapped and delimited ASCII files, can also be used to translate text data in a map (using the Translate using Allocation Table option in the map). If you import data into an A-Table, you import not only the source and target sides but also the correspondence between the items. Importing data into an A-Table will clear all existing entries in the allocation table. You can import items into either a new A-Table or an existing one. The source data from which you import should contain two columns, one representing the source and the other the target. In the case of a D-Cube, the selection consists of the rows D-list and a D-list formatted column on a single page.

Steps to use a D-List or D-List from a D-Cube

1. Click Source and select one of the following. D-List D-List from a D-Cube

714 Analyst

Chapter 14: A-Tables (Allocation Tables) 2. Select a library and a D-List name in the Select D-List dialog box, and then click OK. For D-Lists that are part of a D-Cube, select a D-List from the list in the Specify A-Table dialog box, and then click OK. The items of the selected D-List appear as the source dimension items in the A-Table. 3. Select the Attach to D-List check box to ensure that changes in the D-List are reflected automatically in the A-Table. For more information about attaching a D-List, see (p. 718). If you are sure you do not want the dimension items in the A-Table linked to the D-List do not select the Attach to D-List check box. 4. Click Target. 5. Select a target source type from the menu.

Steps to use a mapped ASCII File

1. Click the Source button. 2. Select a library and a file map in the Select File Map dialog box and then click OK. 3. Select a column from the list in the Specify A-Table dialog box and then click OK. The items of the selected column appear as the source dimension items in the A-Table. Note: The Link option is not available. It is only available if the dimension is a D-List. 4. Click Target. 5. Select a target source type from the menu.

Steps to use a delimited ASCII file

1. Click the Source button. 2. Locate an ASCII file in the Select ASCII file to import dialog box, and then click Open. 3. In the Specify A-Table dialog box do the following: Select a separator from the list (Comma is the default). Select a source column from the list (1 is the default). Note: The number of available columns depends on the separator (delimiter) chosen.

4. Click OK. 5. The items of the selected column appear as the source dimension items in the A-Table. Note: The Link option is not available. It is only available if the dimension is a D-List. 6. Click Target.

User Guide 715

Chapter 14: A-Tables (Allocation Tables) 7. Select a target source type from the menu.

Steps to use an ODBC (SQL) database

1. Click the Source button. 2. In the ODBC Logon dialog box do the following: Select an ODBC source. Enter your User ID. Enter your Password. Click Connect.

3. In the Active ODBC Source window do the following: Select a table from the Available tables section. Select a column from the Available columns section. Click OK.

Note: The Link option is not available (it is only available if the dimension is a D-List). 4. Click Target. 5. Select a target source type from the menu.

Steps to use a Cognos Package as a Source

1. From the File menu, click New, A-Table. 2. Click Source, and select Cognos Package Data. 3. Select a package from the drop box. 4. Select a Query Subject. 5. Under the Available Query Items in selected Query Subject list, select the available Query Items in the Query Subject and move them to the Selected Query Items pane. 6. Select the Display preview of selected query item check box to preview the query items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. Click OK. 7. In the Specify A-Table screen, you specify the Query Item that you want as the source. Click OK. 8. Click Target. You can select Cognos Package Data as the target. 9. Select a package from the drop box.

716 Analyst

Chapter 14: A-Tables (Allocation Tables) 10. Select a Query Subject. 11. Select the available Query Items in the Query Subject and move them to the Selected Query Items pane. 12. Select the Display preview of selected query items check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. Click OK. 13. In the Specify A-Table screen, you specify the Query Item that you want as the target. Click OK. 14. In the Specify A-Table screen, you specify the Query Item that you want as the source. Click OK. 15. Create the allocation table entries. The basic technique for adding allocation table entries in the A-Table is to select the source items and then select the target items. 16. Name and save the A-Table

General Steps to Import Data into an A-Table

1. From the A-Table menu, click Import from. 2. Select one of the following sources to import from. A-Table - if you will be importing from another A-Table. Delimited ASCII - if you will use the A-Table in a D-Link using a mapped delimited ASCII file as its source, or if you will use the A-Table to translate text data in a map (using the Translate using Allocation Table option in the map). This option does not allow you to use a fixed width ASCII file, and it supports only the five most common delimiters, whereas you can create a map for an ASCII file delimited by any single character. Data - select a specific hyperplane from a D-Cube. The slice you select from the D-Cube must consist of exactly one page of a D-Cube containing a rows D-List and one column of D-List formatted data. In the resulting A-Table, the rows D-List will form the source side, and the entries in the D-List formatted data column will form the target. The source side of the A-Table will be linked to the rows D-List, and the target side will be linked to the D-List used as format. Mapped (ASCII) Files - if you will use the A-Table in a D-Link using a mapped ASCII file as its source, or if you will use the A-Table to translate text data in a map (using the Translate using Allocation Table option in the map). Normally, this option is the preferred choice; only this option allows you to refresh the import of dimension items. ODBC (SQL) Databases - if you will use the A-Table in a D-Link using an ODBC database as its source.

User Guide 717

Chapter 14: A-Tables (Allocation Tables) Cognos package - if you will use the A-Table in a D-Link using Cognos packages as its source. Before you can import a Cognos package into an A-Table, you must first create a model in Framework Manager and publish the model, or elements of it as a package.

3. Specify the source and target sides of the allocation table and click OK.

Steps to Import a Cognos Package into an A-Table

1. Open an A-Table. 2. From the A-Table menu, click Import from, and select Cognos Package Data. You will receive a message that importing will override all the items in the A-Table. Click Yes to continue. 3. Select a package from the drop box. 4. Select a Query Subject. 5. Select the available Query Items in the Query Subject and move them to the Selected Query Items pane. You must select at least two Query Items. 6. Select the Display preview of selected query item check box to preview the Query Items. The Preview option only works with Query Items that have not been selected, and helps you select the correct Query Items. Click OK. The Query Items are brought into the D-Cube. 7. In the Specify A-Table screen, you specify the Query Items that you want as the source and target side. Click OK. The items are imported into the Source and Target sides of the A-Table.

Attaching a D-List to an A-Table

If you are in doubt, select the Attach to D-List check box. If you do not select the Attach to D-List check box now and you close the A-Table, you will not be able to select it when you reopen the A-Table. If the Attach to D-List option is selected and D-List items are renamed, the dimension item names and the entries in the A-Table are renamed automatically. If items are added to the D-List, the new items appear in the list of dimension items in the A-Table. If items are deleted from the D-List, the items are removed from the list of dimension items in the A-Table and the corresponding allocation table entries are deleted. When the Attach to D-List option is selected the allocation table entries may only contain valid D-List item names. If it is not selected, the allocation table entries may contain any text. For any dimension not linked, the list of dimension items is cut down to those used in allocation table entries when the A-Table is saved and closed. However, for a linked D-List, the list of dimension items is not cut down: it always contains the full list of D-List items.

718 Analyst

Chapter 14: A-Tables (Allocation Tables)

Add A-Table Entries

You can edit existing entries in the allocation table, or type in new entries if required. If you have selected items in the Source dimension items list using Filter Select, Select All or Invert Selection, you can add allocation table entries by selecting the items from the target dimension items list in the usual way. To add many-to-one allocation table entries, select one target item. To add multiple allocation table entries, select as many target items as there are source items selected. If you want to select items in the Target dimension items list using Filter Select, Select All or Invert Selection, you will have to use the Insert Selected button. Note: The Insert Selected button adds complete allocation table entries if both source and target items are selected.

Add Single Allocation Table Entries

Add single A-Table entries to enter new items or manually edit existing items.

Steps to add a single allocation table entry

1. Open or create a new A-Table. 2. Click the source dimension item. It will be highlighted in the source items list. 3. Click the target dimension item. It will be highlighted in the target items list, and the allocation table entry will be added at the end of the existing allocation table.

Steps to add or edit entries manually

1. Create an A-Table. 2. Select a source and target. 3. Type in source and target entries. If the source or the target dimension is a linked D-List, the allocation table entries must contain valid item names. If you enter an invalid name, you will be prompted to choose one of the item names in the D-List. If you type the first few characters of the item name, the full name will be inserted automatically if a unique match is found. If more than one item matches the text you have typed, you will be prompted to choose one item from those which match.

Steps to add many-to-one entries

1. Open or create an A-Table. 2. Select a source and target. 3. Highlight multiple source items. If the entries are not adjacent, hold down Ctrl and then click multiple items. 4. Click one target item only. If you select more than one target item, you will not create many-to-one allocation table entries.

User Guide 719

Chapter 14: A-Tables (Allocation Tables) The allocation table entries are added.

Add Multiple Allocation Table Entries

Add multiple allocation table entries with adjacent source items or with source items that are not adjacent.

Steps to add multiple A-Table entries with adjacent source items

1. Open or create an A-Table. 2. Select a source and target. 3. Drag to include items in the source range, or press Shift+Down Arrow. 4. Drag to include items in the target range, or press Shift+Down Arrow. Ensure to highlight exactly the same number of source and target items. If the number of source and target items you select is different, then only some of the required entries will be added to the allocation table. The allocation table entries are added. Note: If you attempt to add a number of lines, some of which are duplicates, the new lines will be appended at the end of the existing allocation table, the duplicates lines are not added (the original entries are left in place).

Steps to add multiple A-Table entries with nonadjacent source items

1. Open or create an A-Table. 2. Select a source and target. 3. Click an item in the source list. 4. Ctrl+click the remaining items in the source list. You can select adjacent items by holding Ctrl and dragging. Note: You cannot select multiple non-adjacent items from the target items list (the allocation table entries are added when you first release the mouse button in the target list). The allocation table entries are added. Note: Ensure to highlight exactly the same number of source and target items. If the number of source and target items you highlight is different then no new entries will be added to the allocation table.

Duplicate allocation table entries

You can add duplicate allocation table entries in the A-Table. To remove all duplicate entries right-click anywhere in the source or target column and select Remove Duplicate and Empty Lines from the shortcut menu. Duplicate (and empty) entries will be removed when you save the A-Table.

720 Analyst

Chapter 14: A-Tables (Allocation Tables)

Add New Entries for New Dimension Items

When you update a dimension item list in an A-Table, new items may appear. In any reasonably large A-Table it will not be immediately obvious which are the new items. You can hide all the items in the dimension items list that have already been allocated, in order to work with the list of unallocated items.

Steps
1. Right-click a dimension items list. 2. Click Restrict to Unallocated from the shortcut menu. You can also select the dimension items that correspond to selected allocation table entries. 3. To select dimension items that correspond to entries, select one or more (or all) allocation table entries. 4. Right-click within the selection, and then click Show Allocated Items from the shortcut menu. This command will select both the source and target dimension items that correspond to the selected allocation table entries. You can use the same techniques wherever the items have come from, although the way you update the item list in the first place will depend on where the dimension items have come from. If the dimension is a linked D-List, the new items appear automatically when you open the A-Table. If the dimension items were imported from a mapped ASCII file, you can refresh the import as described above. If the dimension items were imported from a delimited ASCII file, an ODBC database, or a D-List that was not linked, you will have to import the items again.

Add One-to-Many Entries

Allocate one-to-many entries to associate one source item with multiple target items.

Steps
1. Open or create an A-Table. 2. Select a source and target. 3. Click one source item only. If you select more than one source item, you will not create one-to-many allocation table entries. 4. Drag to select target items if the target items are adjacent. Allocation table entries are created as soon as the mouse click is released on the target side, so you cannot Ctrl + click to select multiple target items. The allocation table entries are added.

User Guide 721

Chapter 14: A-Tables (Allocation Tables)

Allocate Entries Using Matching Descriptions

You can add allocation table entries for all matching or first matching source and target items, or matching all detail items.

Steps
1. Open or create an A-Table. 2. Select a source and target. 3. Right-click either the source or the target dimension items list. 4. Select Match All, Match Detail, or Match First from the A-Table menu. Match All: Matches all instances on the source side of the A-Table with all matching items on the right of the A-Table. This is particularly useful when matching codes. Match Detail: Automatically matches all detail items. The target side must be linked to a D-List. No calculated D-List items in the target will be paired in the allocation table even if a match is available in the source. Calculated items on the source side will be paired if they match with a detail item on the target side. Match First: Only finds the first instance of the match on the targeted side. You can add allocation table entries for items that match within a particular subcolumn.

SubColumns
This option is unrelated to cutting subcolumns in a D-Link. In an A-Table, identifying subcolumns simply allows you to add allocation table entries for items that match within the subcolumn. You cannot create allocation table entries that use only a portion of the item name in the A-Table. When you choose Match First, only the first matching dimension item in the list will be given an allocation table entry. If the dimension items have been reordered, the first matching item in the list as it is currently ordered will be given an allocation table entry. When the A-Table is closed and reopened, any subcolumns identified are reset. But until then, the Match First option will continue to operate on the subcolumn rather than the complete item name.

Steps to add a subcolumn

1. Click the Cut a SubColumn button. 2. In the Sub-Column dialog box: Click to create the start of column break. Click again to create the end of column break. Click OK to return to the A-Table window.

The Subcolumn Selected box becomes white to show that a subcolumn has been identified (it is gray when no subcolumn has been identified):

722 Analyst

Chapter 14: A-Tables (Allocation Tables) The column breaks you identified are shown in the SubColumn selected box. The first number indicates the first subcolumn, and the second number indicates the second subcolumn. The Selected/Shown/Total box next to the Cut a SubColumn button displays the information about the rows. For example, if you have 10 rows and have 3 of them selected, the number would be "3/10/10". Note that the item names in the dimension items list are not cut down. 3. To add the matching entries to the allocation table, right-click in either of the dimension items lists and choose Match First from the shortcut menu. Entries are added for the first item in the list that matches within the subcolumn identified. Note that the allocation table entries contain the complete item name, not the cut down item name.

Steps to remove a subcolumn

1. Click the Cut a SubColumn button. 2. Right-click the column breaks to delete them. 3. Click OK.

One-Sided Allocation Table Entries

You can have entries in the allocation table that are incomplete. The source side of the entry may be filled and the target empty (or vice versa). The incomplete side of an allocation table entry is highlighted in red. All entries with an incomplete side are automatically removed when you save the A-Table.

Insert Items Buttons

On each side of an A-Table are the Insert Selected and Insert All buttons. If items are selected in either the source or the target dimension items lists, but not in both, these buttons can be used to do the following: Insert one sided allocation table entries if there are not already one-sided entries in the allocation table. Fill incomplete allocation table entries when there are one-sided entries in the allocation table.

When items are selected in both the source and the target dimension items lists, these buttons can be used to add complete entries to the allocation table.

What are one-sided allocation table entries?

You can have entries in the allocation table that are incomplete. The source side of the entry may be filled and the target empty, or vice versa. The incomplete side of an allocation table entry is highlighted in red. All entries with an incomplete side are automatically removed when you save the A-Table.

User Guide 723

Chapter 14: A-Tables (Allocation Tables)

Inserting one-sided allocation table entries

Both the Insert Selected and the Insert All buttons can be used to insert one-sided allocation table entries.

Fill one-sided allocation table entries

If the allocation table already contains one-sided entries, both the Insert Selected and the Insert All buttons can be used to fill the incomplete allocation table entries provided that no items are selected in the source list. To deselect items, right-click the source dimensions list, and then click Deselect All. Normally, one-sided entries are filled in the order in which they appear in the allocation table. However, you can choose which one-sided entry to fill by selecting an entry before clicking the Insert Selected button. To remove one side of one or more allocation table entries (to turn complete allocation table entries into incomplete entries):

Steps
1. Select either the source or target side of the entries. 2. Right-click in the highlighted range and click Wipe Cells from the shortcut menu. The selected entries will be cleared and given a red highlight.

Select target items

You must be careful when selecting target items. If source items are already highlighted, then highlighting one or more target items will add new entries to the allocation table. If you simply want to select the target items, you must first clear the highlighted source items: Right-click in the source dimension items list and select Deselect All from the shortcut menu. This comment does not apply when selecting source items, as all target items are automatically cleared when you select a source item.

Select Source and Target Dimension Items

There are various shortcut menu commands available to help you select (highlight) items in the source or target dimension items lists.

Step
Right-click in either the source or target dimension items lists and select one of the following: Filter Select - to select items which match some specific search text. Select All - to select all items in the chosen dimension. Deselect All - to deselect all items in both the source and target dimensions. Invert Selection - to invert the selection in the chosen dimension - that is, to select all items not selected and deselect those selected.

724 Analyst

Chapter 14: A-Tables (Allocation Tables) If you click Filter Select you must specify your selection criteria in the Filter dialog box, and then click OK.

Change the Source or Target for an A-Table

If the source or target dimension for an A-Table is not a linked D-List, you can change the source or target for the A-Table at any time by clicking Source or Target. All existing allocation table entries are preserved when you import a new list of dimension items. If the source or target dimension for an A-Table is a linked D-List, the Source and Target buttons are unavailable. You can use a different D-List.

Steps
1. Clear the Attach to D-List check box. 2. Select a new D-List. 3. Select the Attach to D-List check box again. Note: Any allocation table entries that do not match items in the new D-List will be removed (replaced with red cells) when you select the Attach to D-List option. All allocation table entries that do match items in the new D-List are preserved. If the new D-List is the same as the old, consider using the next method. If you want to take a copy of an A-Table and a linked D-List it is using, you can copy both the A-Table and the D-List at the same time by selecting the remap references BETWEEN objects option during the copy process. See "Copy Objects" (p. 307).

Managing A-Tables
Manage A-Tables to maintain and edit A-Tables.

Reorder Allocation Table Entries

You can sort the allocation table entries in four different ways. Ascending by Source - to sort the source entries in alphabetical order - the target entries are rearranged accordingly. Descending by Source - to sort the source entries in reverse alphabetical order - the target entries are rearranged accordingly. Ascending by Target - to sort the target entries in alphabetical order - the source entries are rearranged accordingly.

User Guide 725

Chapter 14: A-Tables (Allocation Tables) Descending by Target - to sort the target entries in reverse alphabetical order - the source entries are rearranged accordingly.

Steps to sort the source entries

1. Right-click anywhere in the source column of the allocation table. 2. Select either Sort Ascending by Source or Sort Descending by Source from the shortcut menu.

Steps to sort the target entries

1. Right-click anywhere in the target column of the allocation table. 2. Select either Sort Ascending by Target or Sort Descending by Target from the shortcut menu. Entries in the allocation table are only sorted when you select one of the shortcut menu commands. If you add new entries to the allocation table after it has been sorted, they are added at the end of the allocation table as normal. The order of entries in the allocation table has no effect on the data transferred by a D-Link using the A-Table.

Show and Hide Dimension Items

You can hide items in the source or the target dimension items list if you want to reduce the item list.

Steps to hide dimension items

1. Open or create an A-Table. 2. Right-click anywhere in the list and click Hide Selected from the shortcut menu to hide a single item, or click Hide Unselected to hide all items not selected. You can also hide all items with entries in the allocation table.

Steps to restrict items

1. Right-click anywhere in the source or target list. 2. Click Restrict to Unallocated from the shortcut menu - For information about how the A-Table adapts when dimension items change, see "How the A-Table Adapts when Dimension Item Lists Change" (p. 727). Hidden items are not removed from the item list.

Steps to show all hidden items in a dimension items list

1. Right-click anywhere in the list. 2. Click Show All from the shortcut menu.

726 Analyst

Chapter 14: A-Tables (Allocation Tables)

Change Entry Signs in an Allocation Table

You can change the sign for individual entries in the allocation table. By default, the sign for all lines in the allocation table is positive (+), data in any line whose sign is changed to negative (-) is multiplied by -1 when the D-Link is run. Note: You cannot use an A-Table that uses sign changing in a lookup or accumulation D-Link.

Steps
1. Open an A-Table. 2. Click the +/- button. 3. In the Edit Signs dialog box: Select the appropriate cell in the Sign column. Select ( + ) or ( - ).

4. Click OK to return to the A-Table dialog box. The text (+/-) on the button changes from black to blue to indicate that some entries have had the sign changed. 5. Save the A-Table.

How the A-Table Adapts when Dimension Item Lists Change

Item lists are never static. New items will appear, and old items may be renamed or deleted. Here you will find a description of how the A-Table adapts to such changes. In the sections, Refresh a Dimension Item List from a Mapped ASCII file (p. 728) and Add New Entries for New Dimension Items (p. 721), you will find advice on how to update the allocation table after such changes.

Linked D-Lists
If items are added to a linked D-List, the new items will appear in the dimension items list when you open the A-Table again. Allocation table entries for new items are not added automatically. If items are deleted from a linked D-List, the items and their corresponding allocation table entries will be removed, but not until the next time you open the A-Table. If items that had allocation table entries have been deleted from the D-List, you will see a warning message indicating that entries are being removed from the A-Table when you next open it. Before the A-Table is opened and the deleted items are removed, the A-Table will continue to function as normal. If items are renamed in a linked D-List, the items and their corresponding allocation table entries are updated automatically. You will see the new item names when you next open the A-Table. You cannot delete a D-List in use in an A-Table if it is linked in the A-Table. Note: Local allocation tables in a D-Link that use a D-List are always linked (unless a subcolumn has been cut).

User Guide 727

Chapter 14: A-Tables (Allocation Tables)

Implement D-List changes with a linked D-List

You may open a D-List and an A-Table using the D-List at the same time. If you make changes to the D-List, these changes are not automatically reflected in the A-Table when you save (or implement) the D-List.

To update an A-Table:
Update an A-Table to see what the A-Table will look like when next opened. For example, to remove all unallocated items from unlinked dimensions. Resetting the A-Table is effectively the same as closing and reopening the A-Table.

Steps
1. Save the A-Table if there are unsaved changes you want to keep. 2. Make the A-Table active, and from the File menu, click Reset.

Other dimensions
The situation is different for all other item lists imported from ASCII files or ODBC databases, with unlinked D-Lists. If new items are added to the list, they will not be recognized until the item list is refreshed. Allocation table entries for new items are not added automatically. Similarly, the A-Table will not recognize if items have disappeared from the list until the list is refreshed. Remember that items without allocation table entries are removed from the item list when the A-Table is saved and closed in any case. If you refresh an item list and items that do have allocation table entries have disappeared, the item and its corresponding entries are left in place. If you want to remove the items and their entries from the A-Table, you must delete all the relevant entries in the A-Table. It is not sufficient to delete just the item from the dimension items list, because the item will be reintroduced when the A-Table is next opened while corresponding allocation table entries exist. The A-Table cannot recognize if an item in the list has been renamed. In this case, it is as if the old item has been deleted and a new item added. You must create new allocation table entries for the new item and delete the entries for the old item. Alternatively, it may be practical to edit the existing allocation table entries manually.

Refresh a Dimension Item List from a Mapped ASCII File

When you import the source and/or target dimension items lists from a Mapped ASCII file, the A-Table automatically stores the location and name of the map and the name of the column chosen in the map. You can update the item lists in the A-Table if the source ASCII file changes for the map changes. You can only refresh the import if the map name and location, and the selected column name have not been changed. The A-Table is not dependent on the map. If you change the map name and

728 Analyst

Chapter 14: A-Tables (Allocation Tables) location the references in the A-Table are not updated, you can delete the map, the map will not be listed under Objects Used in the Summary information dialog box, and so on.

Steps
1. Open or create an A-Table. 2. From the A-Table menu, click Refresh Import. The Last Import dialog box appears. It may include no Refresh buttons, one, or two Refresh buttons, depending on which (if any) of the item lists were imported from a map. 3. Click Refresh to refresh a dimension item. After a list has been refreshed, the Refresh button becomes a greyed Done button.

Delete A-Table Entries

If the source and target dimensions in an A-Table are linked D-Lists, the source and target dimension item lists always include the complete list of D-List items. Items in the list may be hidden (p. 726) but not removed. For dimensions other than linked D-Lists, any items not included in the allocation table are removed from the dimension items list when the allocation table is saved and closed. Note: For any dimension except the linked D-List, you can remove dimension items yourself.

Steps to delete individual entries in an Allocation Table

1. Open or create an A-Table. 2. Drag or hold Shift and click to select the entry (or entries) to be deleted. 3. Right-click the selected items, and then click Delete Row. The selected entries are removed from the allocation table. Alternative methods to delete rows: Select entire entries (that is, both the source and target sides of the allocation table entries) and press Delete to remove the selected entries from the allocation table. Ctrl + click a row to quickly delete an entry.

Steps to delete an entire Allocation Table

1. Open an A-Table. 2. Select all the entries in the allocation table, and then press Delete.

User Guide 729

Chapter 14: A-Tables (Allocation Tables) You can select all the entries in the allocation table by selecting both the Source and Target column headings. Click the Source column heading and drag to include the Target column heading.

Steps to remove duplicate Allocation Table entries

1. Open an A-Table. 2. Right-click anywhere in the allocation table not in the source or target dimension items lists, and select Remove Duplicate and Empty Lines from the shortcut menu. This command will also remove any completely empty lines from the allocation table. Duplicate and empty lines are removed automatically when you save an A-Table.

Steps to remove dimension items in an A-Table

1. Right-click anywhere in the dimension items list. 2. Click Remove Selected from the shortcut menu.

730 Analyst

Chapter 15: File Maps

A file map directs the program to put column breaks in an ASCII file (or text file). The file map performs a task similar to the Data Parse commands in spreadsheets. You can use file maps in D-Links to import data from other programs. File Maps can respect regional settings for the thousand and decimal separators, which refers to the regional options in the control panel.

Creating a File Map

The file map divides a file into columns and tells the program whether to use each column for selection or as data. You can then use the file map in a D-Link to import data from another program so that each piece of data is directed to the correct cell in the target D-Cube.

Create a File Map

Create a a file map to specify which columns in an ASCII file correspond to the D-Lists in your Cognos Planning - Analyst model and which columns contain the data to transfer.

Steps
1. From the File menu, click the New File Map button. 2. Select the source file from which you want to extract the D-List items. 3. Click Open.

Map Editor Page 1

On the first page of the map editor, you need to specify the file type (delimited or fixed width) that best describes your data.

Steps
1. In the Delimited group box: Select Delimited (p. 734) for columns of data separated by commas, semicolons, tabs, or spaces. Specify a delimiter - Tab, Space, Comma, Semicolon, or Other. Note: If you select Other, type in a delimiter that is not a tab, space, comma, or semicolon. Select a text qualifier (p. 737).

User Guide 731

Chapter 15: File Maps Select Fixed Width (p. 734) for individual positioning of the column divides separated by spaces.

Note: Selecting Space delimited is not the same as selecting Fixed Width. Fixed width ASCII files may contain many spaces between columns, so you do not want each space treated as a delimiter. Genuine space delimited files are rare. 2. Enter a number to indicate the first item you wish to import in the Start import at Row box. The default option considers data from the entire ASCII file, but using the Start Import at Row option lets you exclude header rows in the ASCII file. Note: Rows that you exclude do not display when you import data from the map. 3. Select or clear Use row as column names if you want to use the column names as D-List items and specify the row to be used. Tip: Each column in the completed file map must have a name so that the columns can be referenced elsewhere in Cognos Planning - Analyst. Thus, it is good practice to give the columns meaningful names. 4. Click Next.

Map Editor Page 2

On the second page of the map editor, you will define the column breaks (p. 734) (applicable only if you clicked Fixed Width on Page 1 of the Map Editor; if Delimited was clicked, the column divides are automatically defined).

Steps
1. Click once at the start of the first column, then hold Shift and click consecutive columns. If you make a mistake, position the cursor over a column divide and right-click to remove it. 2. To move an existing column divide, drag it to the correct position. 3. Click Next.

Map Editor Page 3

On the third page of the map editor, you classify the columns.

Steps
1. In the Specify Column group box: Use for Selection specifies that the column corresponds to a dimension (D-List) in your model. The data in the column relates to the items of a D-List. The column name should relate to the name of a D-List. If a column contains subheadings, you may need to select Use Follow On (p. 741) for the column.

732 Analyst

Chapter 15: File Maps Use as Data specifies that the column contains data you wish to import into the cells of a D-Cube. Often an ASCII file contains multiple data columns. When a file map is used as the source for a D-Link, all the 'Use as data' columns are grouped together into one dimension named DATA. The names of the data columns in the file map become the item names in the DATA dimension. The D-Link always includes an 'item' named @Count in the DATA dimension. You can think of @Count as a data column in the ASCII file which contains the number 1 in every row. If you assign @Count to a target item, the number transferred to the target cell is the number of rows which contributed data to the cell. When a DATA dimension is left unpaired in the D-Link, the empty selection is interpreted as "sum all items except @Count". Skip is used to exclude columns from import. Skipped columns do not generally appear when you refer to the file map (for example, when you use the file map as the source for a D-Link or an A-Table). After a column has been skipped you cannot edit its name or data format.

If you specified Use row as column names on the first page of the map editor, the title for the column is selected from the file. Otherwise columns will be labelled Column1, Column2, and so on. These can be edited by typing over the Name box in the Appearance group box. It is particularly useful to have meaningful names if using the file map again. In addition, you can enter a brief description of the column in the Description box (which is not seen outside of this file map), and specify a color in the Color box. 2. In the Data Format group box do the following: Select Date and specify a date format if the ASCII file contains a column containing dates that will be paired in a D-Link with a timescale D-List using match descriptions. Select Text when a column contains text that you want to import into D-List formatted cells in a D-Cube. Select Number (default) if the data is numeric.

Using the LIB parameter

After a filemap has been created and saved you can edit the name or location of the file to which it refers by using the buttons in the Source box in the top left hand corner. To browse for a new file, use the Browse button. To ensure that the map will always look for the file in the same library folder as itself, you can edit the path to use the LIB parameter. The advantage of this is that the filemap will always be able to find the file regardless of the path to the library containing the analyst objects. This is particularly useful if the library is copied and sent to several users who might store their analyst libraries in different locations.

Steps
1. Ensure that the file targeted by the filemap is saved in the same folder as the filemap itself. 2. Click Edit in the Source section at the top left. 3. Edit the path to read {LIB}\filename where filename is the name of the file. User Guide 733

Chapter 15: File Maps 4. Save the filemap. Note: It is essential to save the filemap in the correct library before attempting to use this feature.

Delimited and Fixed Width ASCII Files

When you are exporting data to an ASCII file, you will usually be able to choose whether you want to export a delimited or a fixed width file. In most cases, using delimited ASCII files is preferable. If the column widths in a delimited ASCII file change, that is, the number of characters in a column changes, the file map for the file will not require editing. The position of the column breaks in a delimited file is determined by the position of the delimiters in the file. Use the following guidelines for delimited files. For comma separated value (.csv) files, use a comma delimiter. For .prn files, use a tab delimiter. For text files (.txt) use space delimiters.

If column widths change in a fixed width ASCII file, the file map for the ASCII file must be edited. The column breaks in a fixed width file are placed at a particular character number. On the other hand, you will have to use a fixed width file if you need to define columns that span two or more real columns, or if your application does not allow you to export to delimited files. If you need to use fixed width files, try to avoid changing the column widths in the file after the file map for the file has been defined. For example, if you are exporting from a spreadsheet, set the column widths consistently before exporting, making sure that these column widths allow for future growth of the column's contents.

Define Columns in an ASCII File

You define the columns of the ASCII file on the second page of the map editor by defining start-of-column and end-of-column breaks. In a fixed width ASCII file, column breaks are not introduced automatically. In a delimited ASCII file, default column breaks are defined automatically on the second page of the map editor. All instances of the delimiter you selected on the first page are replaced with column breaks, except for delimiters found within a field enclosed by text qualifiers. These default column breaks indicate the real columns of the ASCII file. You can add extra column breaks within the real columns to identify new columns if required. You can also move or delete the default column breaks. When exporting, select Fixed Width if the column widths in an ASCII file differ. Generally, select Fixed Width if your application does not let you export to delimited files. We recommend that you try to avoid changing column widths in the ASCII file after a map of the file is defined. For example, if you are exporting from a spreadsheet, set the column widths consistently before exporting. In delimited ASCII files, you can only create new columns within the real columns; you cannot create new columns that span more than one real column.

734 Analyst

Chapter 15: File Maps Note: Real columns are columns that are indicated by normal column bars. Normal column bars do not have overlapping column bars.

Create a Single Column

You create a single column in a fixed width ASCII file by defining a start-of-column break, then an end-of-column break on the second page of the map editor.

Steps
1. From the File menu, click New, File Map. 2. In the Select ASCII file dialog box, locate the source file from which you want to extract the data, and then click Open. 3. On the first page of the map editor, click fixed width. 4. Click Next. 5. On the second page of the map editor: Click at the start of the column to define a start-of-column break. Click at the end of the column to define the end-of-column break. A column bar appears above the ruler to show that you have defined a column successfully.

Note: Leading and Trailing Columns: All columns defined on page 2 of the map editor are indicated by column bars above the character ruler. Characters placed before the first or after the last column break are not defined as columns.

Create Subsequent Columns

You can create any number of columns in a fixed width ASCII file by clicking once at the beginning of a column, and then clicking again at the end of a column on the second page of the map editor. However, you cannot use this method to create a new column that shares an existing column break. If you need to do this, you can define two new column breaks and move one or both of them into the required positions. Alternatively, you can hold SHIFT and click to create consecutive columns.

Steps
1. From the File menu, click New, File Map. 2. Locate the source file from which you want to extract the data. 3. Click Open. 4. On the first page of the map editor, click fixed width. 5. Click Next. 6. On the second page of the map editor. Click before the desired character.

User Guide 735

Chapter 15: File Maps Click another character to define a new end-of-column break. Drag the new column break to the required position.

Create Overlapping Columns in a Fixed Width ASCII File

To create overlapping columns in a fixed width ASCII file, you must use a fixed width ASCII file as a source and be on the second page of the map editor. You cannot create overlapping columns in delimited ASCII files.

Steps
1. On the second page of the map editor. Click a desired character to define the start-of-column break. Click after another desired character to create a new column break.

2. Create the overlapping column. If the new column is completely contained within an existing column and does not share a column break with it, then click before the desired start point and click again at the end point. If the new column does share a column break with the existing column, it is necessary to define the new column breaks out of position and drag them into place.

A new column bar appears above the existing column bar.

Create Duplicate Columns in a Fixed Width ASCII File

To create duplicate columns in a fixed width ASCII file, you must use a fixed width ASCII file as a source and be on the second page of the map editor. You cannot create duplicate columns with delimited ASCII files.

Steps
1. From the File menu, click New, File Map. 2. Locate the source file from which you want to extract the data. 3. Click Open. 4. On the first page of the map editor: Click Fixed Width or Delimited. Select Use row as column names. Click Next.

5. On the second page of the map editor: Locate an existing column.

736 Analyst

Chapter 15: File Maps Hold Shift and click to the right of the existing start-of-column break.

A new column bar over the existing column bar will indicate that there is a column within a column.

Delete Columns or Column Breaks

Delete columns or column breaks in an ASCII File to select the columns for export.

Step to delete a column

Right-click the column bar above the character ruler.

Step to delete a column break

Right-click the column break in the preview window. Tip: Keep in mind that when you delete a column break, you delete all columns that use the column break.

Text Qualifiers
You can specify the text qualifiers for exporting text strings. These can be set to none, single quote or double quote by selecting from the Text Qualifier drop-down box. The text qualifier will be put around D-List items, text, and D-List formatted data cells. The default setting is none. Usually you use the text qualifier only when there is ambiguity. For example, when the character used as the delimiter for the file occurs within entries in the file. Consider the following data.

Employee Name
Catchetori, Paul Berth, Mark

Monthly Salary
6,500 1,300

If this data is held in a comma-delimited ASCII file, text qualifiers are required so that entries containing commas are not separated. Employee Name, Monthly Salary "Catchetori, Paul", "6,500" "Berth, Mark", "1,300" Without text qualifiers, the row that follows: Catchetori, Paul, 6,500 would be interpreted as four columns rather than two. Entries containing the text qualifier are also enclosed by text qualifiers. For example, the data that follows: Estes, "Eric" 3,000

User Guide 737

Chapter 15: File Maps would appear in a comma delimited ASCII file as "Estes, ""Eric"" ", "3,000" The plain number format relates to exporting numbers. It will not control whether or not text qualifiers appear. The format for plain number format uses the regional setting in Control panel for the decimal separator, to set the number of decimal places to the minimum number to ensure complete accuracy, to use no thousand separator, and to show negative numbers with a leading minus sign and have no prefixes or suffixes. In the DCubeExport macro, the new parameter is added: TextQualifier = single, double, or none. This is not case-sensitive. Note: If you have old macros that relied on the plain number format putting double quotes around the text strings, you may need to change these by inserting the option TextQualifier=double in the macro, but usually this is not necessary.

Special Cases for text qualifiers

If the name contains the text qualifier, it will double up the offending character to avoid ambiguity. For example: If you are exporting a text field containing 1/2" Drill bits to a file that uses double quotes as the text qualifier, it gets exported as "1/2"" Drill bits". Again, if a single quote is used in the name and as a qualifier, it gets doubled up for the export. So 12' ladder exported to a file with a single quote as the text qualifier will repeat the single quote to appear as '12'' ladder'. Important: Numbers containing commas as the thousand or decimal delimiter will either need to be exported to a tab separated file or have a text qualifier. Similarly, you should not export data or text fields containing commas to comma-separated files unless you use text qualifiers. The reason for this is that the program reading the file will not be able to distinguish between commas in the data and commas that are column delimiters.

Date and Text Data in File Maps

You can import text data in an ASCII file into D-List formatted cells in a D-Cube or into text formatted cells, and dates in an ASCII file into date formatted cells in a D-Cube.

Import Date Data from a File Map

On page 3 of the map editor for the ASCII file, you must mark columns containing date data as 'Use as data' and select the Date data format option. You must also select the appropriate date format from the drop-down box. The date format you select here should match the format of the dates in the ASCII file. It does not need to be the same as the date format used for the cells of the D-Cube. In the D-Link you must ensure that data from the date formatted data columns is assigned to date formatted cells in the D-Cube.

738 Analyst

Chapter 15: File Maps For example, suppose an ASCII file contains two data columns: Number and Date, which have been given the appropriate data format in the file map. In the D-Link the source DATA dimension will contain the two items, Number and Date (and also @Count). The DATA dimension can be paired with a target D-List in the D-Link - The source item Date should only be matched to a date formatted item (or many date formatted items). The DATA dimension can be left unpaired in the D-Link. First, you should only select one of the source items. If you select Date, the cells in the D-Cube targeted by the D-Link should all be date formatted. Note that this is not the same as saying that every D-List item targeted by the D-Link must be date formatted. For example, you might have just one date formatted item in one of the D-Lists of the D-Cube. In this case you could leave this target D-List unpaired and select the one date formatted item from it. Or you can pair this target D-List, making sure that only the date formatted item is matched.

How dates are imported

When you run a D-Link to bring in dates from an ASCII file, the dates in the date formatted data column are converted to a serial number according to the date format you selected. It is these serial numbers which are actually transferred to the target D-Cube. The serial number for date formats containing a day, a month, and a year code (YY-MM-DD, DD/ MM/YY, and so on) is calculated from the number of days between the January 1st, 1900 and the start of the period. For example, when a D-Link is run, the date 01/02/97 is found in a date formatted data column in an ASCII file. If the DD/MM/YY format has been selected for this column, 01/02/97 is converted to the serial number 35460 (the number of days between January 1st 1900 and February 1st 1997) . It is this number that is transferred to the D-Cube. If the number is assigned to a cell with a numeric format, the cell will display the number 35460. If the number is assigned to a date formatted cell, the D-Cube will use it as a serial number, and display a date according to the date format active for the cell. For example, if the cell has the DD/ MM/YY format it will display "01/02/97", if it has the YYYYMMDD format it will display "19970201", if it has the Weekday format it will display "Saturday", and so on. If in the file map, the same data column had been given the format MM/DD/YY (rather than DD/ MM/YY as above), 01/02/97 would be converted to the serial number 35430 (the number of days between January 1st 1900 and January 2nd 1997). A date formatted data column may contain entries that do not match the date format selected for the column. Any dates that cannot be converted to serial numbers are imported as zero data (bad data is always assumed to be zero). You can create a D-Link to transfer numbers into date formatted cells; they are treated as serial numbers and displayed according to the active date format.

User Guide 739

Chapter 15: File Maps

Import Text Data from a File Map into D-List Formatted Cells
Identify which columns of the ASCII file contain text data.

Steps to use as data

1. Create a File Map. 2. On page 3 of the map editor make sure Use as data is selected in the Specify column drop-down box. 3. Select Text as the Data format for columns containing text data. If the entries in the ASCII file correspond exactly with the text you see in the D-Cube (that is, the items of the format D-List), there is nothing further to do in the file map. However, the entries in an ASCII file may not match the item names in the format D-List. In this case, you must specify how the text in the ASCII file corresponds to the items of the format D-List using a saved A-Table.

Steps to map an ASCII file using an A-Table

1. Create a file map. 2. On page 3 of the map editor do the following: Select the appropriate column. Click Translate using Allocation Table.

3. In the Select objects dialog box do the following: Select a library. Select an A-Table. Click OK.

The name of the A-Table used in the file map is displayed below the Translate using Allocation Table option when the column is selected. The A-Table will translate the text in the ASCII file into valid D-List item names so that the D-Link can assign the correct data to the cells of the D-Cube. Normally the A-Table is a simple one-to-one correspondence, but many-to-one correspondences are also possible where different items in the ASCII file translate to one D-List item. You may not have an A-Table available. If you do not already have an A-Table to do the translation, you must create a new A-Table.

Steps to create a new A-Table

1. Click the File menu, click New, A-Table. 2. Click Source. 3. Select Mapped (ASCII) Files, and then click the appropriate file map. 740 Analyst

Chapter 15: File Maps 4. Click Target. 5. Select D-List, and then select the D-List used as the format D-List - that is, the D-List containing items that appear as text in a D-Cube. Note: Select the Link check box for the target D-List. 6. Specify the correspondence of items. 7. Name and save the A-Table.

What you need to do in the D-Link

In the D-Link you must ensure that data from the text formatted data columns is assigned to D-List formatted or Text formatted cells in the D-Cube. For example, an ASCII file contains a text data column Text so in the D-Link the source DATA dimension will contain the item Text. The DATA dimension can be paired with a target D-List. The item Text must be matched to a D-List or Text formatted target item, otherwise data will not be imported by the D-Link. On the other hand, the DATA dimension could be left unpaired with the item Text (only) selected. In this case all the D-Cube cells targeted by the D-Link should be D-List or Text formatted. This is not the same as saying that all D-List items targeted by the D-Link must be D-List or Text formatted. You might, for example, leave one target D-List unpaired and select one D-List or Text formatted item from it.

How text is imported

If importing to D-List formatted cells, the text in the ASCII file, or the text translated by an A-Table in the file map, is compared to the item names in the format D-List. When text is found that matches an item name in the format D-List, the text is converted to the Item ID (p. 111) of the D-List item. It is this number that the D-Link actually assigns to cells in the D-Cube. The D-Cube then displays the corresponding item name from the format D-List in these cells. Any text data in the ASCII file that cannot be matched to a D-List item is imported as zero data (the D-Cube will display these cells as blank cells). If you select text formatted data columns in a D-Link, you must target D-List or Text formatted cells. However, you can assign numeric data to D-List formatted cells. If the underlying number in a D-List formatted cell is a valid Item ID in the format D-List the corresponding item name is displayed in the cell. If not, the D-Cube displays a blank cell.

Follow On
The Follow On option allows you to allocate data in an ASCII file based on subheadings found in the file.

User Guide 741

Chapter 15: File Maps You identify the columns that contain subheadings by selecting Use FOLLOW ON on page 3 of the map editor. For Use FOLLOW ON to function, the column must be specified as Use for Selection.

Steps
1. Select the column (it must be marked Use for selection). 2. Select the Use FOLLOW ON check box to activate Follow On for the column.

What does Follow On do?

In the following ASCII file, Row 1 contains the column headings and rows 2 through 10 contain the data you want to import.

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10

Division
0033 France

P&L Line
Sales Sales Tax Cost of Sales

Values
100 18 62 200 35 124 300 53 186

0049 Germany

Sales Sales Tax Cost of Sales

0001 USA

Sales Sales Tax Cost of Sales

Assume you need to allocate data from the Values column based on the subheadings found in the Division column. So in the file map for this file, you must select the Use FOLLOW ON option for the Division column. Division and P&L Line have been marked Use for selection and Values marked Use as data. Suppose this data is to be imported into a D-Cube containing a Divisions D-List (0033 France, 0049 Germany, and 0001 USA) and a P&L D-List (Sales, Sales Tax, and Cost of Sales). You could create a D-Link in which Division is matched to Divisions, and P&L Line to P&L. In both cases, all three source items are matched to the corresponding target D-List items by either match descriptions (p. 233) or a local allocation table (p. 242). When this D-Link is run, data is assigned to the P&L D-List as normal, data in a row is assigned according to the contents of the P&L Line column in that row. However, because follow-on is set

742 Analyst

Chapter 15: File Maps for the Division column, data is assigned to the Divisions D-List according to the last item matched from the Division column. Thus data in Row 1 is assigned to 0033 France - The Division column in Row1 contains the item 0033 France, which was matched in the D-Link. Data in Rows 2 and 3 is assigned to 0033 France - The Division column in Rows 2 and 3 does not contain an item matched in the D-Link, but because follow-on is set for this column, the last matched item (0033 France) is used. The next matching item in the Division column (0049 Germany) is found in Row 5. The last matching item (0001 USA) is found in Row 8. So, data in Rows 5 to 7 is assigned to 0049 Germany, and data in Rows 8 to 10 is assigned to 0001 USA.

An alternative view
When you set Follow On for a column, you are effectively copying the subheadings down into all the rows to which they apply. For example, when we set Follow On for the Division column in the ASCII file above, we determined that D-Links would interpret the ASCII file as follows:

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10

Division
0033 France 0033 France 0033 France 0049 Germany 0049 Germany 0049 Germany 0001 USA 0001 USA 0001 USA

P&L Line
Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales

Values
100 18 62 200 35 124 300 53 186

Which rows will a subheading apply to?

As shown above, data is assigned to the last item matched in a Follow On column. In other words, only when a new matching item is found in a Follow On column does the subheading change.

User Guide 743

Chapter 15: File Maps Which items are matching items is determined entirely by the D-Link definition: Items may be matched in a match descriptions pairing, or they may be matched by an allocation table entry in a local allocation table pairing. Items not matched in one of these two ways will not be used as subheadings. In practice, this means that you should not leave follow on columns unpaired in a D-Link. It also means that you should be careful about which items are matched and unmatched when you pair a follow on column. For example, consider the ASCII file used above.

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10

Division
0033 France 0033 France 0033 France 0049 Germany 0049 Germany 0049 Germany 0001 USA 0001 USA 0001 USA

P&L Line
Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales

Values
100 18 62 200 35 124 300 53 186

As before, the Division column has follow on set in the file map, and Division is paired with a Divisions D-List in a D-Link. Suppose that in the D-Link, the items 0033 France and 0001 USA are matched, but 0049 Germany is not matched, either not matched by match descriptions or without a matching entry in an allocation table. In this case, data from Rows 2 through 7 will be assigned to 0033 France, and data from Rows 8 through 10 to 0001 USA. Leaving 0049 Germany unmatched in the D-Link has not simply caused the data for 0049 Germany to be rejected, but it has caused the data for 0049 Germany to be assigned to 0033 France. Effectively, leaving 0049 Germany unmatched in the D-Link has determined that the D-Link will interpret the ASCII file as follows:

Row 1
Row 2 Row 3

Division
0033 France 0033 France

P&L Line
Sales Sales Tax

Values
100 18

744 Analyst

Chapter 15: File Maps

Row 1
Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10

Division
0033 France 0033 France 0033 France 0033 France 0001 USA 0001 USA 0001 USA

P&L Line
Cost of Sales Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales

Values
62 200 35 124 300 53 186

Use Follow On and Overlapping Subheadings

Often subheadings appear in the same column as the line items to which they apply, or in an overlapping column. In this case you must define two separate columns (p. 735) on page 2 of the map editor: One for the line items and one for the subheadings. One of these columns will form the dimension containing the line items. The other column will form the dimension containing the subheadings, which must have follow on set on page 3 of the map editor. Consider the following file:

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9

Division
0033 France

P&L Line
Sales Sales Tax Cost of Sales

Values
100 18 62 200 35 124 300 53

0049 Germany

Sales Sales Tax Cost of Sales

0001 USA

Sales Sales Tax

User Guide 745

Chapter 15: File Maps

Row 1
Row 10

Division

P&L Line
Cost of Sales

Values
186

In the ASCII file above, Division and P&L Line appear as two separate columns. However, the same data can appear in an ASCII file like the following:

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10 Row 11 Row 12 Row 13

Division/P&L Line
0033 France Sales Sales Tax Cost of Sales 0049 Germany Sales Sales Tax Cost of Sales 0001 USA Sales Sales Tax Cost of Sales

Values

100 18 62

200 35 124

300 53 186

If you wanted to import this data to a D-Cube containing a Divisions D-List and a P&L D-List, you would do the following: On page 2 of the file map, you would create a duplicate column (p. 736) of Division/P&L Line. On page 3 of the file map, you rename the two duplicate columns as Division and P&L Line. Then you would select Use FOLLOW ON for the Division column (both Division and P&L Line are marked Use for selection). After saving this file map, you create a D-Link (p. 215) to import the data. The source dimension P&L Line is matched to the target D-List P&L. Only the P&L items from P&L Line are matched, the division names are not matched. The source dimension Division is matched to the target D-List Division. This time, only the branch names are matched; the P&L items are not matched. Note: The items may be matched by matched descriptions or a suitable allocation table. 746 Analyst

Chapter 15: File Maps Effectively, the way you defined the file map and D-Link has determined that the D-Link interprets the ASCII file like the following:

Row 1
Row 2 Row 3 Row 4 Row 5 Row 6 Row 7 Row 8 Row 9 Row 10

Division
0033 France 0033 France 0033 France 0033 France 0033 France 0033 France 0001 USA 0001 USA 0001 USA

P&L Line
Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales Sales Sales Tax Cost of Sales

Values
100 18 62 200 35 124 300 53 186

Note: Rows 2, 6, and 10 will be rejected when the D-Link is run because there is no valid entry in the P&L Line column.

Drill Down and Follow On

When you drill down on data that has been imported from a mapped ASCII file using Follow On, the source data is presented as the D-Link interpreted it when it was run. The relevant subheading appears in its own column, for every row of data imported.

Dummy Maps
You can create a file map for an ASCII file that is not yet available, providing you have a good idea of how the ASCII file will be structured. You do this by creating a dummy map, which uses dummy data (ambiguous data) instead of a named ASCII file. As you create the dummy map you specify the structure of the dummy data. You can save a dummy map, and when the real ASCII file becomes available, change its source from the dummy data to the real ASCII file.

Steps to create a dummy map file

1. From the File menu, click New, File Map.

User Guide 747

Chapter 15: File Maps 2. Type a name for your dummy data instead of selecting an ASCII file, but make sure you do not enter the name of a real ASCII file. 3. Click Open. 4. Click Yes when you are warned that the selected file you entered could not be opened, and you are given the option to create a map using dummy data. 5. In the File Specification dialog box do one of the following: Click Delimited and then specify a delimiter and the columns in a file. Click Fixed Width and then specify the characters per line.

6. Click OK. 7. Define and save the dummy map as if you were creating a normal file map. You can also substitute a real ASCII File for dummy data.

Steps to substitute a real ASCII file for dummy data

1. From the File menu, click Open, File Map. 2. In the Select File Map dialog box: Select a library. Select a dummy map. Click OK.

3. In the File Error dialog box, click Reselect file. 4. Click OK. 5. In the Select ASCII file dialog box, select an ASCII file. 6. Click OK. The Map will be opened and the map definition will be applied to the chosen ASCII file. Keep in mind that the map definition may need to be edited if the structure of the real ASCII file differs from the structure of the dummy data, as specified by the map definition. Alternatively, you can change dummy data to real ASCII data.

Steps to change dummy data to real ASCII data

1. Open a dummy Map. 2. Select Use Dummy data. 3. Click OK. 4. Click Browse and select a real ASCII file. 5. Click Open. 748 Analyst

Chapter 15: File Maps If you open a map that uses a real ASCII file and the ASCII file cannot be found or is open in another application, you can choose Use Dummy data to open the map and apply the map definition to dummy data, or Reselect file to choose a new ASCII file (or the usual ASCII file, if it has become available).

ASCII Files
ASCII stands for American Standard Code for Information Interchange. It is a file consisting of a standard set of characters, numbers, and punctuation marks readable by most programs. There are various types of ASCII files that use different methods to separate one column of numbers from another. Aligned columns, text (.txt) files, comma separated value (.csv) files and tab separated files are all different kinds of ASCII files. Sometimes ASCII files are also known as flat files. An ASCII file map tells the import program where the columns of data start and end. It is a method of parsing rows of data into columns used for selection and columns used for data. Importing data using mapped ASCII files lets you set the column breaks exactly where they are needed in fixed-width ASCII files. A file map tells the import program where column breaks should occur, which columns contain text or codes, and which columns contain data. After the file map is created, it can be used repeatedly to import data on a regular basis.

Effects of Changing an ASCII File

Changes in the structure (the arrangement of columns) of a source ASCII file will have an impact on file maps using an ASCII file and on D-Links using these file maps. Changing the source file of a file map for one with a different structure will have similar effects. The impact of various changes is described below.

Using a different ASCII file

You can change the source file for a file map by opening the file map, clicking Browse, and then selecting a new ASCII file. If an ASCII file is deleted, renamed, or opened in another application and you attempt to open a file map that used the ASCII file, you will be given the option to select a new ASCII file or apply the file map definition to dummy data. If you attempt to run a D-Link using the file map, you will get an error message stating, File not found. Keep in mind that when you change the source ASCII file for a file map, the new ASCII file may have a different arrangement of columns to the old ASCII file.

Column names in the file map

The columns of a file map are known elsewhere (in D-Links) by the column name given in the file map. Column names are first entered on page 3 of the map editor when you create a new file map. You can edit existing column names by opening the file map, and then changing the names. The column names are not changed unless you edit them.

User Guide 749

Chapter 15: File Maps If, on page 1 of the file map, you selected a row to use as column names, the text in this row was imported and used as the default column names on page 3 of the file map. If the text in this row of the ASCII file changes, the column names in the file map are not changed. Note: You will have to go back to page 1 of the file map if you want to import the new text.

Renamed columns and D-Links

If you rename a column in a file map, D-Links using the file map must be edited. The effect on the D-Link is much the same as when a column is deleted from the file map.

Effects of Changing Delimited ASCII Files

How the file map adapts to changes in a delimited ASCII file can be predicted if you remember that each column in the file map for a delimited ASCII file is defined by the following: The column number in the ASCII file. The first column in the ASCII file lies to the left of the first delimiter, the second column lies between the first and second delimiters, and so on. Column properties applied by the file map - the column name, the column type and format, and so on.

So, you can apply a file map to any ASCII file, or even to 'dummy' data. The column properties defined in the file map are applied to the columns of the ASCII file according to their position in the ASCII file.

Running D-Links after an ASCII file has changed

There is nothing stopping you running a D-Link after the structure of the source ASCII file has changed, and before the file map for the file has been updated. The D-Link may not be able to run at all. But, if it does run, it is unlikely to transfer data in the way you intended. For example, if the mode is set to 'Fill', the D-Link may simply assign zero data to all the cells within its target area. So, if you think the structure of an ASCII file might have changed, open the file map for the file and check it before running D-Links which use the file map.

If column widths change

If the column widths change in a delimited ASCII file, you do not need to update file maps using the ASCII file, or D-Links using these file maps unless you have cut subcolumns from the real columns of the delimited file.

If columns are rearranged

If columns are rearranged in a delimited ASCII file, the file map definition does not update. You will have to edit the file map to update the properties of the rearranged columns, including the column names. For example, two columns, Values and P&L Line, are exchanged in an ASCII file. In the file map, the column named Values will contain profit and loss items, and it will still have all the properties of the old Values column; for example, it will still be marked Use as data. 750 Analyst

Chapter 15: File Maps Remember that D-Links recognize the columns in a file map by their name, so D-Links using the file map will now have a P&L Line dimension paired as before, but containing the data from the old Values column.

If columns are added

If new columns appear in a delimited ASCII file, the file map is not automatically extended. If the new column is added to the end of the file, it is excluded from the file map definition (that is, not seen on page 3 of the file map), and the file map will function as before. If the new column appears at the beginning or in the middle of the file, the columns to the right will move one place right, taking the properties of the column they move into. The column that was previously last is excluded from the file map definition. You will have to edit the file map to update the properties of any column that has been moved over. To include columns that have been excluded, you must go back to page 2 in the file map and edit the column breaks. D-Links using the file map will run, but normally you have to edit them. For example, a file map has two columns: P&L Line ('Use for selection') and Values ('Use as data') . If a new column (containing branch names) is added at the beginning of the ASCII file, the column named P&L Line will contain branch names, and the column named Values will contain profit and loss items (it will still be marked 'Use as data'). The third column, containing the Values data, will be excluded from the file map. If you add new columns in a file map, they are automatically included in D-Links using the file map. If you add a new 'Use for selection' column, D-Links will have a new unpaired source dimension with an empty selection. If you add a new 'Use as data' column, D-Links will have an extra item in the DATA dimension.

If columns are deleted

If columns disappear from a delimited ASCII file, the file map will be truncated when next opened. If the last column in an ASCII file is deleted, the last column in the file map becomes completely empty, and it will be removed when the file map is next opened. If any other column in the file is deleted, the columns to the right move one place left, taking the properties of the column they move into. The last column becomes empty, and it will be removed when the file map is next opened. You will have to open the file map and update the properties of any columns which have been moved over. (You will be warned when you open the file map that it is being truncated). You will then have to edit the D-Links which use the file map. Before the file map is opened and saved, D-Links using the file map will still see the name of the last column in the file map, though it is now completely empty. The D-Links will still run, but are unlikely to transfer the correct data. After you have updated the file map, most D-Links using the file map cannot be run. D-Links using the file map will run if the column removed from the file map was a 'Use for selection' column left unpaired with an empty selection. But, otherwise, if you attempt to run the D-Link you will see an error message indicating that columns are missing from the file map. When you then open the D-Link to edit it, you will see one of two messages.

User Guide 751

Chapter 15: File Maps If 'Use as data' columns are missing from the file map, you are told that the 'data definitions' in the file map have changed, and asked whether you want to update the D-Link. Click Yes to open the D-Link with the missing column removed from the list of items in the DATA dimension. If 'Use for selection' columns are missing from the file map, you will see a dialog box which tells you the name of the column which can no longer be found, and asks you whether you want to use another column in its place. Click Yes to choose an unused column of the file map which should replace the missing column in the D-Link (any allocation table or list of selected items is preserved) . Click No to go directly to the D-Link, if the missing column was unpaired it will have been removed, if it was paired if is removed as soon as you break the pairing.

Effects of Changing Fixed Width ASCII Files

How the file map adapts to changes in a fixed width ASCII file can be predicted if you remember that each column in the file map for a fixed width ASCII file is defined by the following: The character numbers at the start and end of the column in the ASCII file. For example, characters 10 to 20 OF THE ASCII file. Column properties applied by the file map (the column name, the column type and format, and so on).

So you can apply a file map to any ASCII file (or even to dummy data). The column properties defined in the file map are applied to the columns of the ASCII file according to their position in the ASCII file. The file map for a fixed width ASCII file updates in much the same way when column widths change, or when columns are rearranged, added or deleted. The effects on D-Links when a delimited file map changes have been explored previously (p. 750). The same effects are observed when a fixed width file map changes.

Column widths change

If column widths change in a fixed width file, column breaks in the file map are not moved. You will have to edit the column breaks in the file map. Open the file map and click Edit Breaks.

Deleting columns
The column breaks are left in place whatever happens to the source file.

Effects of Changing the Source ASCII File for a D-Link

Often, you must create a number of similar D-Links to bring in data from similar ASCII files. Suppose you have a D-Link which takes data from a particular Mapped ASCII file. Now, you have a second ASCII file, the same as (or similar to) the first, from which you want to take data. You could copy the file map for the first ASCII file, then change the copied file map to point to the new ASCII file (and edit the definition if necessary), then copy the D-Link, change its source from the first to the second file map, and update the D-Link definition.

752 Analyst

Chapter 15: File Maps However, you will lose most of the D-Link definition when you change its source. Instead, you could copy the D-Link and the file map together, thereby preserving references between the objects, then change the copied file map to point to the new ASCII file and edit the definition if necessary. Finally edit the D-Link definition, if necessary.

User Guide 753

Chapter 15: File Maps

754 Analyst

Chapter 16: Analyst Publish

Using Analyst Publish, Analyst users can publish D-Lists, D-Cubes, and plan data from any Analyst library to a star-style schema that is consistent with that produced by Cognos Planning - Contributor. The data can then be used either as a source for a data mart or warehouse, or with Cognos 8 Business Intelligence. You publish data using the Analyst Publish wizard, or the @publish macro when you need to publish in batch. Analyst Publish creates a database containing a number of tables and views based on the publish layout and options that you select. Alternatively, you can choose to target a database created outside of the Analyst Publish process, with one exception: you cannot target a Contributor publish container from Analyst. Choose from these types of publish layouts: The table-only layout. This layout is designed to give users greater flexibility in reporting on Planning data, and for use as a data source for other applications. The view layout. This layout is intended for backward compatibility with previous releases of Contributor and Analyst. We recommend that applications dependent on the view layout be migrated to the table-only layout to obtain storage and performance efficiencies.

Dimensions for Publish

In both layouts, for each selected D-Cube you can choose a D-List that is designated as the dimension for publish. In doing so, a separate column is created for each data item in the dimension. For the Table-only layout, a default dimension is selected. For View Layout, no default dimension is selected. Selecting a dimension speeds the publishing process because fewer rows are written to the target database. Candidate dimensions for publish typically contain formatted D-List items or items by which the business tracks or measures performance. Such items are often numeric. We recommend that each item of the selected dimension contain uniform data. This means that for every row, the data is of the same type: numeric, text, or date/time.

Handling Nonuniform Data

It is possible that slicing the D-Cube along the dimension for publish results in non-uniform data. For example, cell data along any item of the dimension for publish may be of mixed types. Because of this, rows of data for an item may be of different types.

User Guide 755

Chapter 16: Analyst Publish In the table-only layout, where non-uniform data exists and must be preserved, you must explicitly select each data type; otherwise, the data type is excluded. For example, selecting the numeric and date/time options guarantees that only numeric and date/time data are written to the corresponding numeric and date/time columns; text is excluded. As a result, if the first row of an item is a numeric value, it is stored in the corresponding numeric column. The remaining data type columns for that item are populated with null values. In the view layout, data type uniformity is handled by storing all values in text columns. An associated fact view (fv) is created using the sum hierarchy to view only numerical information.

Selecting a Dimension for Publish for Reporting

It is important to carefully consider which dimension for publish you select when publishing data to be reported on. The dimension for publish is the D-List whose items become columns in the fact table. That is, instead of becoming an ID which links to a hierarchy table, the items in the selected D-List are converted to actual fact table columns.

Why the Choice of Dimension for Publish is Important

If you are reporting using a non-OLAP reporting tool, the publish is performed using SQL behind the scenes. Data is reported in columns, which are sorted, grouped and summarized in the rows. This means that you can perform actions such as inter-column calculations and independent formatting in the columns, but the rows can only be summarized. You can potentially build SQL reports with intra-row calculations, but it would take you longer to build and costs more to maintain. Note that rows and columns here are SQL terms. Columns and rows can be switched around within a report, and indeed this is often the case in financial reports.

Selecting Your Dimensions for Publish

The primary calculation D-List is often used as the dimension for publish. However there are situations where other D-Lists (such as Time or Versions) are more suitable. Your choice of dimension for publish is driven by a number of factors, and the Planning and BI designers should work together to select the appropriate one for reporting. The Planning designer may find it easier to build another cube than to report from an existing cube. Carefully consider which dimension for publish to use, because if you change it after you have started to build reports, you may need to rework existing reports. The following D-List attributes identify a likely dimension for publishing: It contains a combination of text, numeric and date items (mixed data types). It contains numeric items with different display formats such as ##% and #,###.##. Your reports need to do additional calculations between items in the D-List. You need to treat some of the D-List fields separately for reporting purposes. The dimension for publish impacts the time the Publish takes to run. Even though there are fewer columns to create, more rows are written to the datastore, and this takes time to write.

756 Analyst

Chapter 16: Analyst Publish Tip: In some circumstances you may not want a dimension for publish. In this case your publish table has one row for every combination of dimension and you would leave all the processing and formatting intelligence to the reporting tool. Using the Table-only layout, you must select a dimension for publish, so to achieve equivalent functionality, add a D-List to the cube containing one item, and use this D-List as the dimension for publish.

Understanding the Publish Process

Publishing from Analyst is an incremental operation. You can publish D-Cubes and D-Lists originating from different libraries to the same target database; however, they must be published using the same publish layout. Metadata tables maintain the library ID, library name, globally unique identifier and model timestamp for each object that has been published. Before publishing from Analyst, the model metadata (GUIDs and timestamps) are compared to the information maintained in these tables. In case of overlap between the existing contents of a target database and the planning information to publish, the following actions are taken: If the information to be published already exists in the database, it is ignored. If the D-Cube information to be published is more recent than the information stored in the database, a new export table is created to replace the previous database information for that D-Cube. If the D-List information to be published is more recent than the information stored in the database, all objects from the same library are replaced with the new information.

The Table-only Layout

For the table-only layout, the publish options are stored in the publishoptions table organized by library. Whenever the library is published, the contents of the publishoptions table are reviewed. If the library was already published, the options in the Analyst Publish wizard are set to the values in the publishoptions table and applied. These values cannot be edited in the Analyst Publish wizard.

Table-only Publish Layout

Using the table-only publish layout means that you can Select a D-List as the dimension for publish Generate data columns in their native order, which preserves the original order when reporting Choose to publish only detail plan data (no derived items) Select whether to prefix the dimension for publish column names with their data type to avoid reserved name conflicts

The following types of tables are created when you publish using the table-only layout.

User Guide 757

Chapter 16: Analyst Publish

Table Type
Items (p. 758)

Description
Describes the D-List items.

Prefix / Name
it_ sy_ for the simple hierarchy, cy_ for the calculated hierarchy.

Hierarchy (p. 760) The hierarchy information derived from the D-list is published to two associated tables. Export (p. 762) Contains published D-Cube data

et_ an_

Annotation (p. 763) Contains annotations for each D-Cube.

Metadata (p. 763) Contain metadata about the publish P_APPLICATIONCOLUMN, tables. There are three metadata P_APPLICATIONOBJECT, and tables. publishoptions.

Database Object Names

Database object names are derived from the Planning object names. The maximum length of table and column names are as follows.

Type of Name
Column Table

MS SQLServer
128 128

IBM DB2 UDB

30 128

Oracle
30 30

Names cannot begin with a number or underscore (_), and can include the following characters: a through z 0 through 9 _ (underscore)

Items Tables
Only D-Lists referred to from published D-Cubes are published. One items table is created for each D-List. It contains one row per item. The name of the table is generated from that of the D-List and the prefix it_. The items tables have the following columns.

758 Analyst

Chapter 16: Analyst Publish

Column
itemid dimensionid itemname displayname disporder itemiid

Description
Unique identifier for the item Unique identifier for the D-List Name of the Item Display name of the item Display order specified in Analyst, which is zero-based D-List integer identifier for the item, which is used as the primary key

Hierarchies
There is no model construct for specifying items hierarchies in Analyst. Instead, hierarchies are derived from user specified equations. There are two types of hierarchies currently supported depending on the type of reporting performed on data; complete hierarchies and simple summary hierarchies. Complete hierarchies should be used to produce reports on the entire contents of cubes. Complete hierarchies are used more to organize cube data and are not used to perform rollups and calculations in the reporting engine. The rules that govern the generation of complete hierarchies in the cy_ tables are as follows: The parent of a given item is the first simple sum that references the item. If this sum does not exist, it is the first non-sum calculation that references the item. If neither exists, the item is a top-level item.

Simple summary hierarchies are used when only leaf data is being published and rollups are performed from the reporting engine. The rules that govern the generation of these hierarchies are as follows: The parent of a given item is the first simple sum that references it. In the case where there are multiple candidates for the parent of a node, the node is assigned to the first parent in iid order and the other candidate parents are considered to be leaf nodes in the hierarchy. In the case where a parent cannot be identified that way and the node is not a simple sum, the item is considered to be a root node (referred to as orphan node in the rest of the text).

Simple summary hierarchies are not necessarily complete because all items that are part of a D-List may not necessarily be part of the hierarchy.

User Guide 759

Chapter 16: Analyst Publish The starting point for the production of these hierarchies is the graph of items dependencies produced when equations are parsed. This graph specifies all parent/child relationships between items. Because the simple summary hierarchy is limited to simple sums, it is possible that sub-hierarchies be detached from the main hierarchy and be moved to the top.

Hierarchy Tables
The complete hierarchies are published to the cy tables while the simple summary hierarchies are available in the sy_ tables. These tables all have the same format. They contain the following columns for each level of the hierarchy:

Column
levellevel_number_guid levellevel_number_iid levellevel_number_name levellevel_number_displayname levellevel_number_order

Description
Globally unique identifier of the item D-List integer identifier of the item Item name Item display name Item order in the hierarchy

Simple hierarchy tables are created by the publish table-only layout and are intended to be used when there are simple parent-child relationships between D-List items which can be sum totaled. The purpose of this is to allow a reporting tool to automatically generate summaries for each hierarchy level, or for use with applications that do not require pre-calculated data, such as staging source for a Data Warehouse. In the four examples below, D-List items are represented by letters, and the relationship between items are drawn as lines. Parent nodes are D-List items which are calculated from child node dependencies. Leaf nodes are D-List items without child node dependencies. All nodes have their values shown in simple parenthesis (5) and in addition, leaf node codes are shown in curly braces {0}. 0: Direct child of a simple sum node. 1: The leaf has multiple parents. 2: The leaf item is part of a sub-hierarchy and has been moved to the root. 3: The leaf item is an orphan.

760 Analyst

Chapter 16: Analyst Publish

Example 1: Simple Summaries (Best Practice)

The left pane is an example of simple hierarchies with values. The right pane is an example of simple hierarchies with values and leaf node codes.

Example 2: Multi-Parent Summaries (Leaf Node with Multiple Parents)

Leaf node [E] has more than 1 parent, so parentage is assigned to the first parent in the IID order. Parent node [D] becomes a leaf node, and node [F] becomes orphaned and is moved to the root.

Example 3: Non-Simple Summaries

Parent node [P] is the product of leaf nodes [S] and [T]. Leaf nodes of non-simple summaries get moved to the root. Since node [P] became a leaf node, node [S] and {T] were orphaned and moved to the root.

User Guide 761

Chapter 16: Analyst Publish

Example 4: Sub-Hierarchy of Non-Simple Summary

Node [B] is the product of node [C] and [E]. Node [C] has its own simple summary hierarchy. Since non-simple sums are not included in the hierarchy, node [B] becomes a leaf, node [E] and [C] become orphaned and moved to the root, but node [C] keeps its sub-hierarchy because it is a simple sum.

Export Tables
Cell data for the selected cubes are published to the export tables. If you select the Include Roll Ups option, the export tables contain all the data, including calculated data. Otherwise, the export tables contain only non-calculated fact data. By default, calculated values are published. Users who report against published data that contains only fact data use the reporting tool to aggregate the calculated items when grouping with the hierarchical dimensions. A number of options control the generation of the export tables (prefix et_). Publish only uniform cube data. This is achieved by selecting the Create Columns With Data Types Based on the Dimension for Publish option. In this case, the data type of each item of the Dimension for publish is used for the columns of the export tables. In the case where individual cell types differ from that of the corresponding columns, the corresponding cell data is simply not published and an informative message is displayed to that effect. Control the data types being published by selecting only those of interest, where only data of the specified types are published. When more than one data types is selected, you get multiple columns for each item in the export tables, one column per data type selected. For example, if both numeric data and dates are selected, two columns are created per item in the dimension for publish. Include the original formatted numeric and date values, which are stored in the text column. This is useful when the original format cannot be easily reproduced in the reporting tool application. Control the level of detail of the information to publish to either publish entire cubes, or publish only leaf data and let the reporting engine perform the rollups. The summary hierarchy as specified in the sy_ tables must be used to perform the rollups. Leaf cells are those that correspond to leaf nodes of the simple summary hierarchies.

762 Analyst

Chapter 16: Analyst Publish

Data Types Used to Publish Data

The following data types are used for publishing data.

Data Type
TEXT DATE DOUBLE INTEGER

MS SQLServer
VARCHAR(8000) datetime float integer

IBM DB2 UDB

CLOB date float int

Oracle
VARCHAR2(4000) timestamp float NUMBER(10)

The prefixes text_, date_, and float_ are used to identify the data types of columns in the tables and the suffix _[count] is used to guarantee name uniqueness.

Annotations Tables
The Analyst Publish wizard provides you with the option to publish annotation information along the dimension for publish. The annotations tables (prefix an_) have the following three columns for each item of the dimension for publish.

Column
iid_DB_Item_Name DB_Item_Name_user_id DB_Item_Name_date DB_Item_Name_annotation

Description
A unique identifier for an item in a dimension The last user who updated the annotation The last date that the cell annotation was updated The text of the annotation

The cell value is not published in the annotation table.

Metadata Tables
The information contained in the metadata tables is used to trace back published information to its originating D-Cube or D-List. Metadata about the publish tables is maintained in the following tables P_APPLICATIONCOLUMN P_APPLICATIONOBJECT publishoptions

User Guide 763

Chapter 16: Analyst Publish dimensionformats

The P_APPLICATIONCOLUMN Table

The columns of the P_APPLICATIONCOLUMN are as follows.

Column
objectname columnname displayname columnid objecttypeid columntypeid

Description
Name of the object Name of the column Display name of the associated Planning object Unique identifier for the associated Planning object Type of Planning object Descriptor for the column, one of NAME, DISPLAYNAME, GUID, VALUE, DISP_ORDER, and so on. Order of the column in Analyst Logical type of the column

columnorder logicaldatatype

The P_APPLICATIONOBJECT Table

The description of each database object created during a publish operation is maintained in the applicationobject table. The columns of the P_APPLICATIONOBJECT table are as follows.

Column
objectname displayname objectid

Description
Name of the object Display name of the associated Planning object Unique identifier of the associated Planning object

764 Analyst

Chapter 16: Analyst Publish

Column
objecttypeid

Description
Type of Planning object: DIMENSION_ITEMS DIMENSION_HIERARCHY DIMENSION_CALC_HIER DIMENSION_SIMP_HIER EXPORT_TABLE ANNOTATION_TABLE

dataststoretypeid objectversion lastsaved

Type of target database object (typically TABLE) Complete version number of the product Timestamp corresponding to the last time the planning object was saved in Analyst Analyst library ID

libraryid

The publishoptions Table

All publish options are stored in the publishoptions table and are organized by library. The options in the publishoptions table are applied during incremental updates (p. 757). The columns of the publishoptions table are as follows.

Column
libraryid libraryname publish_text_option publish_date_option

Description
Specifies the Analyst library ID Specifies the display name of the associated library Indicates whether the Text option is selected for publish Indicates whether the Date option is selected for publish Indicates whether formatted numeric and date values are selected for publish Indicates whether calculated values are included for publish

publish_formatted option

publish_leaves_only_option

User Guide 765

Chapter 16: Analyst Publish

Column
publish_numeric_option

Description
Indicates whether the Numeric option is selected for publish Indicates whether the Analyst Publish wizard creates columns with data types based on the dimension for publish Indicates whether zero or blank values are included or filtered out Specifies that the name of columns for numerical values should be prefixed with float_ in the export tables

publish_use_dfp_option

publish_filter_null_option

publish_column_prefix_option

The dimensionformats Table

Contains formatting information for the items of the dimension for publish to enable Cognos 8 reporting. The columns of the dimensionformats table are as follows.

Column
dimensionid itemid

Description
Globally unique identifier of the dimension for publish Globally unique identifier of the item of the dimension for publish One of percent, numeric or date String indicating how negative values have to be reported Number of decimal places for numerical values Integer for the scaling factor of numerical values Characters to use for zero of blank values

formattype negativesignsymbol

noofdecimalplaces scalingfactor zerovaluechars

Creating a Table-only Publish Layout

You can select the library and D-Cubes to be published, and specify the target database as well as its connection parameters.

766 Analyst

Chapter 16: Analyst Publish Only saved D-Cubes can be published. If you are working in an Analyst session, you must save the D-Cubes first. To target an empty database or schema, you must have drop table and view privileges. Otherwise, you must have Administration privileges on your database server before you can publish.

Steps
1. Click the Publish button. The Analyst Publish wizard appears and shows the list of available publish layouts. 2. Select Table-only layout and then click Next. The Database Options screen appears. 3. Under Datastore provider, select one of SQL Server, Oracle, or DB2/UDB. 4. In the (ODBC) DSN box, select the DSN (p. 773). 5. In the User ID box, enter your user ID. 6. In the Password box, enter your password. 7. In the Database name box, enter the database name that you wish to use for the target database. 8. If you use SQL Server, in the Database file path box, specify the path to the folder that will contain the files for the new database. 9. If you use Oracle or DB2 / UDB, click Tablespace to specify different tablespaces for relational Data, indices, or blobs. The specified tablespaces must already exist for the target database. Note: If you a creating publish tables with many items in the data dimensions, ensure your tablespace limit is set to a sufficient size. 10. If you want, click Test Connection. 11. Click Next. The D-Cube Selection screen appears. 12. Select the library from which you want to publish data. A list of all the D-Cubes associated with that library appears in the D-Cubes list under the Libraries list. 13. In the D-Cubes list, select one or more D-Cubes to be published and click Next. The Data and Table Options screen appears. 14. Create table columns: To use the item types from the dimension for publish as the table columns, select Create columns with data types based on the dimension for publish. For more information, see "Dimensions for Publish" (p. 755).

User Guide 767

Chapter 16: Analyst Publish To manually select the data types that will be part of the publish process for each measure, select Only Create the following columns. 15. Select or clear the check boxes as required. Include roll ups: Selecting this check box includes all items, including calculated items. Clearing this option only publishes leaf items, and therefore fewer rows. You can recreate the calculation in your reporting tools by linking the et and sy tables. Include zero or blank values: Clearing this check box means that empty cells are not populated with zeros or blanks. This can speed up the process of publishing data substantially, depending on the number of zero or blank cells. Prefix column names with data types: Select this option if you wish the column name to be prefixed with the data type to avoid reserved name conflicts. Include annotations: Publishes annotations in the an_ tables.

16. Click Next. 17. Select a D-List for each D-Cube. By default, None is selected. 18. If you want to preview the published columns for the selected D-Cube, click Preview and then OK. 19. Click Next and then click Finish. The summary screen appears and shows information about the model being published.

View Publish Layout

The view publish layout as supported in Contributor and Analyst version 7.2 is compatible with previous Planning data solutions. It is intended for backwards compatibility only. We recommend that non-Cognos applications currently dependent on the view publish layout be migrated to use the new table-only publish layout because of the improvements in publish performance, data storage efficiency and incorporation of best practices.

Database object names

Database object names are limited to 18 lowercase characters, and are derived from the Planning object names. Numeric suffix of the form _1 can be added to database object names to avoid name collisions. Prefix are used to classify object names into the following categories: 768 Analyst Prefix for tables describing D-List items: it_ Prefix for export tables containing published cube data: et_ Prefix for tables describing the D-List hierarchy: hy_ Prefix for tables describing the D-List calculated hierarchy: cy_

Chapter 16: Analyst Publish Prefix for tables containing cube annotations: an_ Prefix for views defining a user-readable (i.e. not Globally Unique Identifiers) version of cube data (et_ tables): ev_ Prefix for views defining a subset of cube data corresponding to items in hierarchy tables (hy_) : fv_ Prefix for views defining a subset of cube data corresponding to items in the complete hierarchy tables(cy_): cv_

D-Lists
D-Lists referred to from published D-Cubes are published to the it_tables. The schema is the same for all D-Lists. The first column gives the unique identifier of the item, the second column is the unique identifier of the containing D-List, and the remaining columns are the item name, display name, and the item order in the D-List (the order is zero-based). One table is created for each D-List part of the Publish operation and it contains one row per item. The name of the table is generated from that of the D-List according to simple rules which allow for a suffix to be added to the name to guarantee its uniqueness.

itemid
dimensionid itemname displayname disporder

Unique identifier for the item

Unique identifier of the D-List Item name Item display name Display order specified in Analyst

D-Cube Data and Export Tables

Cell data for the selected cubes are published to the et_ tables, one row per cell. These tables contain the coordinate for each cell of the cube and the corresponding cell value. There is one column per D-List to store the item GUID along that dimension, plus an additional column for the cell value (published as a blob or varchar depending on the target DBMS). In Planning, a cell value can contain a date, a double, or text. Cell data can be published as a formatted value specified from Analyst, or as a raw value.

Annotations
For each cell annotation part of a cube, the following information is published to the an_ tables: The coordinate of the cell in the form of GUIDs along each dimension The cell annotation itself User Guide 769

Chapter 16: Analyst Publish The id of the user that created the annotation The creation date of the annotation

Metadata
Metadata about the publish tables is maintained in two tables: applicationobject and applicationcolumn. The information contained in those two tables is sufficient to trace back any published information to its originating D-Cube or D-List. The description of each database object created during a publish operation is maintained in applicationobject. The schema for that table is as follows:

Columns of table P_APPLICATIONOBJECT Column

objectname displayname objectid Objecttypeid

Description
Publish table name Display name of the associated Planning object Unique identifier of the associated Planning object Type of Planning object: DIMENSION_ITEMS, DIMENSION_HIERARCHY, DIMENSION_CALC_HIER, EXPORT_TABLE Type of target database object (typically TABLE) Complete version number of the product Timestamp corresponding to the last time the planning object was saved in Analyst Analyst library id

datastoretypeid objectversion lastsaved

libraryid

Columns of table P_APPLICATIONCOLUMN Column

objectname columnname displayname

Description
Publish table name Column name Display name of the associated Planning object

770 Analyst

Chapter 16: Analyst Publish

Column
columnid objecttypeid columntypeid

Description
Unique identifier of the associated Planning object Type of Planning object Descriptor for the column: column refers to the following model properties: NAME, DISPLAYNAME, GUID, VALUE, DISP_ORDER, etc. Column order in Analyst Logical type of the column

columnorder logicaldatatype

Views
An ev_view is created to provide a more user-friendly access to its associated export table (et_table) , which contains cube data. In this view, GUIDs are simply replaced by the display name associated with the D-List items, and export value are cast to varchar when published as blobs. A fact view (with fv_prefix) is created for each cube being published and is limited to numeric values by joining the export values from the et_ table to the items in the hy_ tables for the cube. These rules for deriving this hierarchy are explained earlier. A complete view (with cv_prefix) is created for each cube being published and is built by joining the export values from the et_ table to the items in the cy_ tables for the cube.

Creating a View Publish Layout

Use the Analyst Publish wizard to select the library and D-Cubes to be published, and specify the target database as well as its connection parameters. You must have Administration privileges on your database server before you can publish.

Steps
1. Click the Publish button. The Analyst Publish wizard opens and shows the list of available publish layouts. 2. Select View layout and then click Next. The Database Options screen appears. 3. Under Datastore provider, select one of SQL Server, Oracle, or DB2/UDB. 4. In the (ODBC) DSN box, select the DSN (p. 773). 5. In the User ID box, enter your database user ID. 6. In the Password box, enter your database password.

User Guide 771

Chapter 16: Analyst Publish 7. In the Database name box, enter the name that you wish to use for the target database. 8. In the Database file path box, if you use SQL Server, specify the path to the folder that will contain the files for the new database. 9. For Oracle or DB2 / UDB, click Tablespace to specify different tablespaces for relational Data, indices, or blobs. The specified tablespaces must already exist for the target database. Note: If you are creating publish tables with many items in the data dimensions, ensure your tablespace limit is set to a sufficient size. 10. Click Test Connection to test the connection. (Optional.) 11. Click Next. The D-Cube Selection screen appears. 12. Select the library from which you want to publish data. A list of all of the D-Cubes associated with that library appears in the D-Cubes list under the Libraries list. 13. From the D-Cubes list, select one or more D-Cubes to be published. Only saved D-Cubes can be published. If you are working in an Analyst session, you must save the D-Cubes first. 14. Select or clear the check boxes as required.

Check box
Include zero or values

Description
Includes cells with blank or zero values. Clearing this option can substantially speed up the process of publishing data, depending on the number of zeros or blank cells.

Include annotations Use plain number formats

Includes annotations in published D-Cubes. Selecting this option removes any numeric formatting for the purposes of export. It exports to as many decimal places as are needed, up to the limit stored on the computer. Negative numbers are prefixed by a minus sign. No thousand separator, percent signs, currency symbols, or other numeric formats that were applied on the dimension or D-Cube are used. Plain Number Format uses the decimal point (.) as the decimal separator.

15. Click Next. The Dimensions for Publish screen appears. 16. Select a D-List for each D-Cube (Optional). For more information, see "Dimensions for Publish" (p. 755). 17. To preview the published columns for the selected D-Cube, click Preview and then OK. 772 Analyst

Chapter 16: Analyst Publish 18. Click Next and then click Finish. The summary screen appears and shows information about the model being published.

Publishing Using the Command Line

You can publish from the command line with the Analyst Batch Job executor CepBatch.exe, and an Analyst batch job that uses the @Publish macro. Using the command line allows publishing to be scripted, or to occur as a scheduled task. To publish from the command line, type the following syntax from the Cognos install directory: CepBatch -b -1 "MyPublishJob" [ -2 MyUserId] [ -3 MyPassword]]

Option
-1 -2 -3

Purpose
Name of job created with the Analyst Batch Utility wizard Specifies the userID Specifies the userID's associated password

Note: The Analyst 7.2 command line publish executable AnalystPublisherCmdLine.exe is intended for backward compatibility only. We recommend that applications dependent on AnalystPublisherCmdLine.exe be migrated to use CepBatch.exe.

Create a DSN for the Database Server

Analyst Publish uses ODBC, so to access SQLServer, Oracle, or DB2 UDB, you must create a user or system DSN. The DSN specifies the database server being used. The following ODBC level III drivers are supported: MS SQLServer Oracle 8 or higher IBM DB2 ODBC

Steps for Microsoft SQL Server

1. In the Windows Control Panel click Administrative Tools, Data Sources (ODBC). 2. Click the System DSN tab. 3. Click Add, then select the SQL Server DBMS driver. 4. In the Create a New Data Source to SQL Server page, provide the requested information: 5. Provide connection information for the DSN.

User Guide 773

Chapter 16: Analyst Publish Whether to use NT authentication or SQL Server authentication is highly dependent on your SQL Server installation. If necessary, consult your database administrator. The user specified must have privileges to create and populate databases. 6. Select the Use ANSI quoted identifiers and Use ANSI nulls, paddings and warnings check boxes. 7. Select the Perform translation for character data check box. 8. Click Finish. You can now test the connection.

Steps for Oracle

1. In the Windows Control Panel click Administrative Tools, Data Sources (ODBC). 2. Click the System DSN tab. 3. Click Add and double-click Oracle native DBMS driver. 4. In Oracle ODBC Driver Configuration screen, provide the requested information, and leave the default check box selections. 5. Click Test Connection to check whether the ODBC environment is configured properly. It connects to the database specified by the Data Source Name definition, and you are prompted for your username and password. 6. Click Finish.

Steps for Microsoft ODBC for Oracle

1. In the Windows Control Panel, click Administrative Tools, Data Sources (ODBC). 2. Click the System DSN tab. 3. Click Add, and double-click the Microsoft ODBC for Oracle DBMS driver. 4. In the Microsoft ODBC for Oracle Setup page, provide the requested information. 5. Click Finish. You can now test the connection.

Steps for DB2 UDB

1. In the Windows Control Panel click Administrative Tools, Data Sources (ODBC). 2. Click the System DSN tab. 3. Click Add and double-click IBM DB2 ODBC driver. 4. In IBM DB2 ODBC-Add screen, provide the requested information, and then click OK. 5. To test the DSN, select it and click Configure. The CLI/ODBC Settings dialog box appears. 6. Enter your user ID and password and click Connect.

774 Analyst

Chapter 16: Analyst Publish 7. Click OK.

Set up Microsoft SQL Server 2000 Desktop Engine as a Database Server

Analyst Publish supports Microsoft SQL Server 2000 Desktop Engine (MSDE), so that you can publish to a low maintenance database management system. It is an alternative that provides a simple migration path from a desktop database solution to a SQL server solution if the application grows too large for MSDE 2000. You must download and install MSDE 2000, which is free from Microsoft.

Steps
1. On the Microsoft Web site, search for MSDE 2000 Release A. 2. Follow the download instructions for MSDE 2000 Release A. 3. Read the installation prerequisites and instructions in the ReadMeMSDE2000A.htm file that was copied to the root of the directory you specified. 4. Specify the setup parameters in an .ini file. Here is an example of the content of a setup.ini file: [Options] INSTANCENAME="MSDENewInstance" SAPWD="AStrongPassword" SECURITYMODE=SQL TARGETDIR="C:\MSDENewInstance" The option "SECURITYMODE=SQL" must be specified for the SQL Authentication logon used in the Analyst Publish feature. 5. Start the installation by typing the following on the command line: setup /settings "setup.ini" 6. You can now create a DSN for the Microsoft SQL Server data source on the local machine (p. 773). If the INSTANCENAME parameter was specified at installation, the setup installed an MSSQL instance different from the default one. Its name must be specified. 7. Specify a SQL Server Authentication.

Reporting Directly From Publish Tables

Cognos Planning published data is stored in standard datastore tables. You can report directly from these tables, using the Generate Framework Manager Model functionality to help in the process. You must not run reports during the publish process, as you may get inconsistent results. Also, if destructive changes have been made to the Planning environment, the publish tables may no longer match the ones defined in your reporting metadata model.

User Guide 775

Chapter 16: Analyst Publish It is best practice to isolate the business intelligence reports from the source data environments by creating a reporting datastore. This allows you to add value by bringing in data from other applications. For example, perhaps there is some data which was optimized out of the Cognos Planning application but would be useful for your reports. At its simplest, this datastore could be a straight copy of the publish tables as produced by Cognos Planning. It could also be a traditional data mart or an extension to your existing data warehouse. Dimensionally-aware ETL tools such as Cognos Data Manager can also be used to ensure that a single version of data runs through all your Cognos Planning and business intelligence applications. If you report directly from Cognos Planning tables, be aware of the following:

Scenario and Version Dimensions

Cognos 8 is usually set up to automatically aggregate data around grouped items. If your report does not contain all the dimensions from a fact table then the data for the unspecific dimensions is aggregated. Normally, this is desirable behavior, but the Scenario and Version dimensions that are often used in planning applications are not suited for aggregation. One technique to handle this is to set up a mandatory filter on your cube tables in Framework Manager, forcing the reporting environment to either prompt for values whenever the fact table is used, or to have separate filtered query subjects for each version.

Precalculated Summaries
Be aware of precalculated summary levels in the published tables when using the Table-only publish layout. You may find that they complicate your data model. You can disable them by clearing the Include Roll Ups publish option. If you do not do this, then the data for precalculated summary levels is published into the same tables as the detail items. If you are using item tables (named it_D-List_name and containing an unstructured flat list of all items in the hierarchy) this is acceptable. If not, you may have reporting issues as your queries need dimensional context in order to avoid double counting. Note also that the publish take longer to run (more data points to write). If you are not using the item tables then the reporting environment could confuse users because there are separate hierarchy table aliases for each level in Framework Manager.

Generate Framework Manager Model Wizard

Generate Framework Manager Model creates a set of Framework Manager models from Cognos Planning data published in a table-only layout, including a base model and a user model. It also publishes a package to Cognos Connection.

Base Model
The base model contains the definitions of objects required to access Cognos Planning data published in a table-only layout. The objects include table definitions (query subjects), dimension information, security filters, and model query subjects.

776 Analyst

Chapter 16: Analyst Publish

User Model
The user model provides a buffer to contain the modifications made by the Framework Manager modeler. When modifications are made to the Contributor application, or to the Analyst model, the base model can be updated using Generate Framework Manager Model. Then, the user model can be synchronized using the synchronize option in Framework Manager. The synchronization process makes all the modifications to the base model appear in the user model. This is done by synchronizing the user model with the base model and by reapplying any changes made to the user model by the modeler to the synchronized user model. The package published to Cognos Connection is published from the User Model.

Configuring Your Environment

Before you can use Generate Framework Manager Model, you must configure your environment. Do the following: Note: It is recommended that you install the Administration components (Analyst and Contributor Administration Console) on the same machine as the Planning Server components. Ensure that you can access Cognos Connection For example, in the address bar of your Web browser, type http://computer_name/cognos8/. Ensure that you can publish the Cognos Planning data in a table-only layout. Configure the Publish datastore to use the logon and password of the datastore server, not Trusted Connection.

Understanding Generate Framework Manager Model

When you generate a Framework Manager model, the following occurs: A Cognos 8 data source is created for the Table-only publish container. The Framework Manager script player creates models and packages object actions from the Table-only publish metadata publishes packages

Objects in the Generated Framework Manager Model

The models generated by Generate Framework Manager Model contain the following objects.

Folders
Framework Manager contains a series of folders containing objects of the same type. These folders are created in two top-level folders: Physical View and Business View. The Physical View Folder contains all the database query subjects and the Business View folder contains all the dimension and star schema objects.

User Guide 777

Chapter 16: Analyst Publish

Database Query Subjects

Database query subjects are created for all the tables needed to provide access to Cognos Planning data. The tables included in the model depend on the query subjects selected, and may include cube export tables dimension item tables dimension derived hierarchy tables dimension complete hierarchy tables annotation tables

Joins
Joins are created between related tables, such as the cube export data tables and derived hierarchy tables.

Column Usage
The usage attribute of the query items contained in the database query subjects are set to the correct value: fact, identifier, or attribute.

Security Filters
If the models are generated from a Contributor application, security filters are created for each cube export data query subject. The filters grant users access to the same e.List items as in the Contributor application. A security filter is created for every user on every cube export data query subject. If the models are generated from Analyst, no security filters are created.

Regular Dimensions
For each derived hierarchy and complete hierarchy query subject, a regular dimension object is created and saved to the Derived Dimensions and Complete Dimensions folders respectively. These folders are located in the Business View folder.

Measure Dimensions
For each cube export table, a measure dimension object is created. It is stored in a folder that has the same name as the cube. These folders are located in the Business View folder.

Star Schema Groupings

For each cube in the model, some star schema groupings are created. If the derived hierarchy lists are selected, a star schema grouping is created using the derived dimensions. If the complete hierarchy lists are selected, a star schema grouping is created using the Complete Dimensions folders.

Data Source
Data source refers to the data source created in the Cognos Connection Portal.

778 Analyst

Chapter 16: Analyst Publish

Package
A package contains all the objects in the Framework Manager model. The administrator of the package is the user generating the model. In Contributor, the users who have access to the package are the users of the Contributor application. In Analyst, the only user to have access to the package is the user generating the model.

Objects Created in Cognos Connection

When generating a Framework Manager model using Generate Framework Manager Model, a data source is added to Cognos Connection. The associated connection string and signon is also created if applicable.

Create a Set of Framework Manager Models

You can create a set of Framework Manager models that can be used to create reports to access published data in a table-only layout.

Steps
1. Publish the data that you want to create the model for using the Table-only layout. You must use an untrusted connection. 2. In Analyst, click Tools, and select Generate Framework Manager model. 3. In the Welcome page of the wizard, click Next. 4. Configure the following properties:

Property
Datastore Provider

Description
Choose from: SQL Oracle DB2/UDB

Login (ODBC)DSN User ID Password Database name Select the DSN used to access the database server Enter the database username Enter the database password Enter the database name for the published data. The last database published is used by default.

User Guide 779

Chapter 16: Analyst Publish 5. Test your connection by clicking the Test Connection button. 6. Click Next. 7. Select Create a New Framework Manager Model and click Next. 8. Select where on the local computer to create the Framework Manager model. 9. Type the package name, browse to the location of the package in Cognos Connection, and optionally type a screentip and description. 10. Select the cubes to include in the model. 11. Select the type of query subjects to include in the model: unformatted lists, derived hierarchy lists, and complete hierarchy lists. 12. Click Finish. The selections made in this wizard are saved for the next time the extension is run and are used when updating a model.

Update a Framework Manager User Model

You can update a Framework Manager model to include changes to the Planning model. The new Base Model is re-imported and any changes you made to the User Model are reapplied.

Steps
1. In Analyst, click Tools, and select Generate Framework Manager model. 2. In the Welcome page of the wizard, click Next. 3. Enter the database options for the data store of the model that you are updating. For more information, see "Create a Set of Framework Manager Models" (p. 779). 4. Select Update an existing Framework Manager Model. 5. Enter the Project Location. The User Model path already contains the model file that was last created. 6. Follow the wizard instructions to update, remove, and regenerate the Base Model. The wizard finishes. 7. Open Framework Manager and open the User Model. 8. From the Project menu, click Synchronize and then click Run the script from the starting point.

Generate Transformer Model Wizard

Use the Generate Transformer Model wizard to generate a Cognos Transformer Model from a table-only database layout and create Cognos PowerCube(s). You can publish secured or unsecured

780 Analyst

Chapter 16: Analyst Publish PowerCube(s) to a Business Intelligence package in Cognos Connection and view its content using any of the Cognos 8 studios. You can also view unsecured PowerCubes with PowerPlay Series 7. With the Generate Transformer Model, you can: generate a Transformer model generate a Transformer model and a PowerCube create a PowerCube from an existing Transformer model

The GenerateTransformerModel Macro

You can also use the @GenerateTransformerModel macro to automate the steps you perform in the Generate Transformer Model wizard."@GenerateTransformerModel" (p. 697).

Configuring Your Environment

Before you can use the Generate Transformer Model Wizard, you must configure your environment. Do the following: If you create PowerCube(s), ensure that you can access Cognos Connection For example, in the address bar of your Web browser, type http://computer_name/cognos8/. Ensure that you can publish your Cognos Planning data in a table-only layout, as this is required to run the Generate Transformer Model wizard. Before you can create PowerCube(s), you must first have Transformer installed and configured on the machines where the Planning Server components are installed.

Generate a Transformer Model

Generate a Transformer Model using the Generate Transformer Model wizard.

Steps
1. In Analyst, click Tools, and select Generate Transformer model. 2. In the Welcome screen, select Generate Transformer model, and/or Create PowerCube(s) and click Next. See "Creating PowerCube(s)" (p. 782). 3. Configure the following properties:

Property
Datastore Provider

Description
Choose from: SQL Oracle DB2/UDB

User Guide 781

Chapter 16: Analyst Publish

Property
Login (ODBC)DSN User ID Password Database name

Description

Select the DSN used to access the database server Enter the database username Enter the database password Enter the database name for the published data. The last database published is used by default.

4. (Optional) Test your connection by clicking Test Connection. 5. Click Next. 6. Enter the path to the Transformer model location and the PowerCube location. Note: If you are not creating a PowerCube, then you do not have to enter a path to the PowerCube location. If you do enter the path, it will be stored in the model as the default location to create a PowerCube. The paths must be located on the server. UNC paths can be used. 7. Select the contents to add to the Transformer model. If more than one library has been published to the database, you can select a library. Select the D-Cubes that you want included and click Next. 8. If you selected to create PowerCube(s), you can optionally create a Business Intelligence package. enter a package name browse to a location for the package in Cognos Connection (Optional) enter a description (Optional) enter a tool tip click Next

9. In the Create the Model screen, review your information and click Finish to create the Transformer Model.

Creating PowerCube(s)
When you create PowerCube(s), do the following: provide the name of a directory on the application server (Optional) enter a UNC path

782 Analyst

Chapter 16: Analyst Publish If you create a PowerCube without also generating a Transformer Model, then you must enter an existing Transformer Model in the Transformer Model location. You can publish secured or unsecured PowerCube(s) to a Business Intelligence package in Cognos Connection and view its content using any of the Cognos 8 studios. You can also view unsecured PowerCubes with PowerPlay Series 7.

Model Changes that Impact the Publish Tables

Cognos Planning models are flexible and change to map the changes in the business. Changes can affect reports that are run off planning data. The following topics describe the impact that various changes to the Planning model have on publish tables in the data.

Changes to Dimensions Change D-List (not Dimension for Publish)

Add items None as long as the number of New columns added. Existing SQL levels in the hierarchy remain the still works. same. None as long as the number of Columns are deleted. Processing levels in the hierarchy remain the referring to these columns must be same. modified. None unless name filters are used D-List formatted items are stored in the BI application. in the fact columns as text rather than as a foreign key. As a result, text exported from previously published data may not match this text. A full publish resets the text in the Publish tables, but review external datastores where these items have not been normalized. Add hierarchy levels New columns created in dimension None. tables. Existing reports will not fail but level naming may no longer be correct. None.

Dimension for Publish

Delete items

Rename items

Delete hierarchy levels Columns deleted in dimension tables.

User Guide 783

Chapter 16: Analyst Publish

Change

D-List (not Dimension for Publish)

Dimension for Publish

Reorder items

None.

Datastore columns are reordered but SQL still works. SQL still works.

Refresh items from the datastore Rename the D-List

None.

Dimension table name changes.

None, as long as the D-List is not used in D- cube where it is not the dimension for publish.

Changes to D-Lists that are used as D-List Formatted Items

Fact table name change.

Changes to D-Cubes Change

Reorder dimension

Affect
None. The column sequence in the datastore may change but this does not impact reports. Assuming that the new dimension is not the dimension for publish, data for all items in the new D-List are automatically summed if no action is taken. For most lists this is desirable, but care needs to be taken if the dimension contains scenarios or versions.

Add dimension

Delete dimension

Links to the dimension table are removed from the fact table. Reports referring to items in that dimension are affected.

784 Analyst

Chapter 17: Printing and Previewing

Setup, preview and print Analyst D-Lists, D-List formulas, D-cubes, nested macros, library objects, and cell annotations. You can also print an object in .csv format to use in Microsoft Word or Excel. To print or preview BiF specifications, see "Steps to locate Built in Functions" (p. 42) to print or preview the specifications of certain BiFs.

Print Setup
You can set the orientation, printer, column width, and font in the Print D-Cube dialog box. These options will determine the format of the D-Cube when it is printed. When selecting orientation, portrait will print text across the 8.5-inch side of the page between the left and right margin; landscape will print text across the 11.5-inch side of the page between the left and right margin.

Steps to change print orientation

1. Open a D-Cube and make a selection. 2. From the File menu, click Print or Print Preview. 3. In the Orientation area, select Portrait or Landscape.

Steps to set column widths while printing

1. Open a D-Cube and make a selection. 2. From the File menu, click Print or Print Preview. 3. In the Column Width area, select or clear Fixed Width. 4. If you selected Fixed Width, set the size of the column widths in the Fixed Width box.

Steps to change fonts

1. Open a D-Cube and make a selection. 2. From the File menu, click Print or Print Preview. 3. In the Font box, specify a font. 4. In the Size box, specify a font size.

Steps to view an identification number (IID)

1. Open an object (p. 43).

User Guide 785

Chapter 17: Printing and Previewing 2. From the File menu, click Print Preview, Preview or click the Summary Info button in the Analyst toolbar.

Previewing
The Print Preview option allows you to view items before they are printed. If you want to make any changes before you print an item, see "Print Setup" (p. 785).

Preview Formulas and Details of a D-List

Before printing, preview D-List formulas and details.

Steps
1. Open the D-List. 2. From the File menu, click Print or Print Preview. 3. Click the General tab. 4. Select Summary info, Description, and Note. 5. Select an orientation - Portrait or Landscape. 6. Click the D-List tab. 7. To display the appropriate D-List information, select Calculations and Usage information. 8. Click Preview. Details of the D-List and its formulas are displayed. 9. To scroll through the pages, click the right preview button or the left preview button. 10. Click Close.

Preview a D-Cube
When using this feature of Cognos Planning - Analyst, you can preview an entire D-Cube or selected ranges of the D-Cube. In addition, you can save the selected range to be previewed (or printed) for repeated use. Also, you can sort the order for printing rows, columns, and pages.

Steps
1. Open a D-Cube. 2. From the File menu, click Print Preview. 3. Click Select to select the items to be displayed. 4. Move items from the Items Available list to the Items included list. 5. Click OK.

786 Analyst

Chapter 17: Printing and Previewing Note: You can save the selection by clicking the Save button, and then specifying a name for the selection. This feature is particularly useful if you want to preview the same selection more than once. 6. On the Print D-Cube screen do the following: Select a printer from the Printer box. Select a font and font size. Select Annotations if you would like to print the annotations at the bottom of the page. Select Fixed width and specify the width (in characters) of the columns. Select Portrait or Landscape depending on the orientation you prefer.

7. Click OK. Details of the D-List and its formulas are displayed. 8. Click the right preview button or the left preview button to scroll through the pages. 9. Click Close.

Preview D-Cube Summary Information

You can preview the details of a D-Cube. This includes the DOS pathname (available to the system administrator only), the owner name, the list of objects (such as D-Lists) used by the D-Cube, and the list of the objects that use the D-Cube.

Steps
1. Open a D-Cube. 2. From the File menu, click Summary Info. 3. Click the General tab. The D-Cube name, library, location (DOS pathname), owner, description (optional), and owner's note (optional) are displayed. You can type a description and an owner's note into the text boxes provided. 4. Click the Objects used tab. All objects that the D-Cube uses are displayed. 5. Click the Usage tab. All objects that use the D-Cube are displayed. This includes D-Links, selections and other objects. In the Usage column there is a description of how the D-Cube is used. For example, a D-Link could use a D-Cube either as a source to export data or as a target to import data.

User Guide 787

Chapter 17: Printing and Previewing

Printing
You can print a D-List and its formulas, a D-cube and its details, nested macros, a list of objects in a library as well as cell annotations. You can also print an object to a .csv file to be used in another program such as Word or Excel.

Print a D-List and Formulas

You can print the D-List details, calculations, usage, security, and format information.

Steps
1. Open a D-List. 2. From the File menu, click Print. 3. In the Print Options dialog box, click the General tab. 4. Select the information: Summary info Description Select the orientation: Portrait or Landscape. Select the output mode for printing: Print Using (path to printer)

- or Export to filetype (CSV or HTML). 5. Click the D-List tab. 6. Select the information to include: Calculations or Usage information. 7. Click Print.

Print a D-Cube
The printing default settings are WYSIWYG for the selection of items to include, the orientation of rows, columns and pages, zero suppression and hiding of details or totals. By default, these settings are taken from the current view of the D-Cube. Although you can change these options they do not get saved with the D-Cube. Instead it defaults to whatever is currently set on the D-Cube.

Steps
1. Open a D-Cube. 2. From the File menu, click Print. 3. Click the D-Cube Data tab to select Font, Size, Annotations, and Column Width.

788 Analyst

Chapter 17: Printing and Previewing Click the Select button to select specific items from each D-List to print only a range of selected pages. Leave this as is to print everything. For information about printing blank selections, see "Sort D-List Items" (p. 143).

Note: Blank selections within pages, even in moderately sized D-Cubes, can total several hundred. If you leave selections blank, all pages in the D-Cube are printed. We recommended that you limit the selections taken from each list. 4. Click the Printer tab to select a specific printer to print to, orientation of final output including Portrait or Landscape. Click Options to choose not only Landscape and Portrait, but also Rotated Landscape, Page Order, Pages Per Sheet, and Paper Quality. Click Advanced to choose Paper Size, Copy Count, Scaling, True Type Font, Advanced Printing Features, and Postscript Options.

5. Click the Margins tab to set Top, Bottom, Left, Right, Header, and Footer margins for printing. 6. Click the Header/Footer tab to select what information you want to appear in the Header, Left Footer, and Right Footer, and select the Top Rule and/or Bottom Rule check box. 7. Click the Zeros tab to select Suppress Zero Rows, Suppress Zero Columns, and Suppress Zero Pages. The zero suppression of totals and details are taken from the current D-Cube view. 8. Click the Show Det/Tot tab to select which D-Cubes to Hide Detail and Totals. 9. Click Print.

Print Nested Macros

You can expand and print nested macros.

Steps
1. Open the macro. 2. From the File menu, select Print, and click the Macro tab. 3. Select the Expand Macro Execute check box. 4. Click Print.

Print a List of Objects in a Library

You can print a list of objects contained in a particular library.

Steps
1. From the File menu, select Library and click Objects. 2. In the Library Functions dialog box, choose the library you want to print from the drop-down menu at the top. User Guide 789

Chapter 17: Printing and Previewing 3. Right-click over the library list and click Print list of objects. A preview displays of the printed list. 4. To print the list, click the Print button.

Print to .csv Files

You can print an object to a .csv file to be used in another program such as Word or Excel.

Steps to print a D-List object to a .csv file

1. Open the D-List you want to print to a .csv file. 2. From the File menu, click Print. 3. From the Print Options dialog box, in the Output Mode area, select the Export to filetype check box and select CSV from the list. 4. Click Browse and specify a location and name for the file. 5. Click Print. The .csv file is exported and named according to your selections.

Steps to print a D-Cube object to a .csv file

1. Open the D-Cube you want to print to a .csv file. 2. From the File menu, click Library and select D-Cubes. 3. From the D-Cube Library Functions screen, select the D-Cube you want to print to a .csv file, and move it to the Objects Selected box by highlighting the D-Cube and clicking the down arrow. 4. From the Print Options dialog box, in the Output Mode area, select the Export to filetype check box and select CSV from the list. 5. Click Browse and specify a location and name for the file. 6. Click Print. The .csv file is exported and named according to your selections.

Print Annotations
You set the orientation, printer, column width, and font in the Print D-Cube dialog box. In addition, you can select to print cell annotations.

Steps
1. Open a D-Cube and make a selection. 2. From the File menu, click Print or Print Preview. 3. In the Annotations area, select or clear Print at the bottom of the page.

790 Analyst

Glossary
access tables
In Contributor, controls access to cells in cubes, whole cubes, and assumption cubes.

accumulation D-links
D-links that consolidate data from a source D-cube to a D-cube based on text data.

administration job
An administration task that runs on job servers and is monitored by the Contributor Administration Console. These tasks are commonly referred to as jobs. Some examples of jobs are reconcile, publish, cut-down models, links.

administration link
A link that enables an administrator to move data between Contributor applications. An administration link can contain multiple applications and cubes as the sources and targets of the link. A link can contain multiple elements which target either the development or the production application. Administration links run using the job architecture and so are scalable.

administration machine
In Cognos Planning, the computer that is used to operate Contributor Administration.

administration server
In Cognos Planning, the server that contains the planning components package (COM+ package) and where control of the online application is maintained. You connect to this machine when you first run Contributor Administration.

application
In Cognos Planning, a Contributor application. Contributor applications are used for the collection and review of data from hundreds, or thousands of Web servers. One application can be used by many users in different locations at the same time.

Application server
See Job Server.

assumption cube
In Cognos Planning, a cube that contains data that is moved into the Contributor application when the application is created or synchronized. It does not contain the e.List. Therefore, data applies to all e.List items, and is not writable. The data it contains is often named "assumption data."

User Guide 791

Glossary

A-table
In Analyst, an allocation table that shows how two lists correspond. It is useful for transferring data when no character matches are possible between lists of items.

BiF
Built in Function. In Cognos Planning a BiF is a special calculation formula that was set up specifically for planning. For example, depreciation, discounted cashflow, forecasting using different drivers, and stock purchase prediction based on future sales.

bounce
In Cognos Planning, a term used to refer to the removal of the currently editing owner of an e.List item in the Contributor Web client. A planner or reviewer may "bounce" the owner.

commentary
In Cognos Planning, commentary represents any additional information attached to Contributor cells, tabs, or e.List items, including both user annotations and attached files. You can use administration links, system links and local links to copy commentary.

contribution
In Cognos Planning, data that is entered into an e.List in the Contributor application.

Contributor Administration
A tool which enables administrators to publish an Analyst business model to the Web, manage access settings and model distribution, and configure the user's view of the model.

cube
A physical data source containing a multidimensional representation of data. A cube contains information organized into dimensions and optimized to provide faster retrieval and navigation in reports. In Cognos Planning, a cube (see also D-Cube) corresponds to a tab on Contributor client user interface.

current owner
In Contributor, the person who is editing or lasted opened an e.List item for edit.

cut-down models
In Cognos Planning, customized copies of the master model definition that have been cut down to include only the specific elements required for a particular e.List item.

datastore
In Cognos Planning, the location where one or more Contributor applications are stored. A datastore contains the information needed to connect to a database supporting the Contributor applications.

792 Analyst

Glossary

D-cube
In Cognos Planning, a multi-page speadsheet made up of two or more dimensions. A D-cube must contain at least two dimensions. In Contributor a D-cube is referred to as a cube.

dimension
In Cognos Planning, the rows, columns, and pages of a cube are created from dimensions. Dimensions are lists of related items such as Profit and Loss items, months, products, customers, and cost centers. Dimensions also contain all the calculations. One dimension can be used by many cubes. In Cognos 8 BI a dimension is a broad grouping of descriptive data about a major aspect of a business, such as products, dates, or markets. Each dimension includes different levels of members in one or more hierarchies and an optional set of calculated members.

D-link
In Analyst, a link that copies information in and out of cubes, and sometimes to and from text or ASCII files.

D-list
An alternative term for dimension.

D-list format
Lets you enter text from another D-List in a row or a column. The format may be used in database-type functions to consolidate data in a similar manner to query-style reports.

drill down
In Cognos Planning, drill down is a technique used to analyze D-Cube data that was imported by a D-Link. You can drill down on any single cell in a D-Cube. If the cell contains data transferred by a D-Link, drill down opens a view of the source data. If the data was imported from another D-Cube, drill down opens the appropriate selection from the source D-Cube. If the data was imported from an external source (a mapped ASCII file or an ODBC database), drill down extracts the relevant data from the source file and displays it in a special drill-down results dialog box. In Cognos 8 BI, drill down refers to the act of navigating from one level of data to a more detailed level. The levels are set by the structure of the data. See also drill up.

e.List
The basis for the structure of a Contributor application. An e.List is a hierarchical dimension which typically reflects the structure of the organization (for example, cost centers and profit centers).

editor
In Cognos Planning, a planner or reviewer who is editing a contribution

User Guide 793

Glossary

extensions
In Cognos Planning, extends the functionality of Contributor Administration and Web Client. There are two types of extensions: Admin Extensions and Client Extensions. Admin Extensions run in the Administration Console. Client Extensions are activated from the tool options on the Contributor Grid.

file map
In Analyst, a file map tells the program how to split an ASCII or text file into columns of data. A file map puts in the divisions, or breaks, between one column of numbers and another. It defines the start point and width of each column of data within an ASCII file, and denotes whether the column is a numeric, text, or date field. If there is only one column, a file map is superfluous. File maps are always necessary when using an ASCII file as the source for a D-Link.

Get Data
In Cognos Planning, a command in the Web client that loads the screen that displays local links and system links.

go to production
In Cognos Planning, a process in the Contributor Administration Console that takes the development application and creates the live production application.

grid
In Cognos Planning, a tabular form for viewing and entering data.

GUID
Global Unique Identifier. A unique internal reference for items in a model. For example, when you add a dimension item, this item is assigned a GUID.

hold
In Cognos Planning, a function that protects a cell against breakback.

import block
In Cognos Planning, a package of data from Analyst or an external system that is validated and prepared for import into a Contributor application. The import block is imported into the Contributor application datastore via a reconcile job.

import link
A function used in Analyst to update the items in a dimension on a regular basis from a source file or database.

794 Analyst

Glossary

job server
In Cognos Planning, a machine that runs the administration jobs. There may be multiple job servers. A job server is sometimes referred to as an application server.

library
In Cognos Planning, the storage location of the model. The library includes a group of connected Analyst objects: macros, reports, D-Links, selections, D-Cubes, maps, A-Tables, D-Lists, and formats. A library is similar to a Windows directory.

local links
In Cognos Planning, a link defined and run by a user in the Web client.

lock
In Cognos Planning, a function that prevents data being entered into cells whether by typing or via a D-Link.

lookup d-links
In Cognos Planning, D-Links that look up data from a source D-Cube based on text data. It uses a database D-Cube as a target.

macros
In Cognos Planning, a single object defined by an administrator to automate a series of Administration tasks in Contributor. Each task is known as a step. In Analyst, a set of commands that have been recorded and grouped together as a single command, which is used to automatically complete a list of instructions in one step.

match descriptions
In Cognos Planning, used to automatically match source and target dimension items with the same name. In addition, match descriptions can be used to perform an allocation by date.

maximum workspace
(MAXWS) The amount of memory reserved for Analyst. May be changed to allow larger models to run more effectively.

model
A physical or business representation of the structure of the data from one or more data sources. A model describes data objects, structure, and grouping, as well as relationships and security. In Cognos 8 BI, a design model is created and maintained in Framework Manager. The design model or a subset of the design model must be published to the Cognos 8 server as a package for users to create and run reports. In Cognos Planning, a model is a group of D-Cubes, D-Lists, D-Links, and other objects stored in a library. A model may reside in one or more libraries, with a maximum of two for Contributor. User Guide 795

Glossary

namespace
For authentication and access control, a configured instance of an authentication provider. Allows access to user and group information. In XML, a collection of names, identified by a URI reference, which are used in XML documents as element types and attribute names. In Framework Manager, namespaces uniquely identify query items, query subjects, and so on. You import different databases into separate namespaces to avoid duplicate names.

offline grid
In Cognos Planning, the application that is used to access a section of an offline Contributor application. The purpose is to enable users to enter or view data while there is no network connection.

owner
In Contributor, a user who is assigned to an e.List item through the Rights screen and is permitted to edit or review it. These rights may be directly assigned, or may be inherited.

planner
In Cognos Planning, a person who enters data in the Contributor application in the Web client.

product application
In Cognos Planning, the version of the Contributor application seen by the Web-client user. The version of the Contributor application that is seen in the Contributor Administration Console is the development application.

protect
In Cognos Planning, a function that is used to prevent data from being typed into a cell. However, data can still be transferred into a protected cell via a D-Link.

publish
In Cognos 8 BI, refers to the creation of a package that makes metadata available to the Cognos 8 server. Information in the package is used to create reports and other content. In Cognos Planning, refers to a function that is used to copy the data from Contributor or Analyst to a datastore, typically so it can be used for reporting purposes.

publish container
In Cognos Planning, a datastore container created specifically to publish data to.

796 Analyst

Glossary

reconciliation
In Cognos Planning, a process that ensures that the copy of the Contributor application that the user accesses on the Web is up to date, for example, all data is imported. Reconciliation takes place after Go to Production has run and a new production application is created.

reviewer
In Cognos Planning, a person who reviews the submissions of reviewers or planners.

rights
In Contributor, assigning rights enables administrators to determine what users can do in a Contributor application. Rights determine whether a user can view, edit, review, and submit data.

saved selections
In Contributor, dynamic groups of items from a dimension or e.List. When used in conjunction with access tables, access tables provide a high level of control over the access or cells. In Extensions, sets of data configured during an export or refresh. A user can choose a saved selection and update just the data without reconfiguring the report or export criteria. In Analyst, sets of data used to save a specific D-Cube orientation, including a selection of rows, columns, and pages for later use. The selected items, sort order, and slice of the D-Cube are all saved in a named selection.

synchronize
In Contributor, a function used to update all cubes, links, and so on in an application when the underlying objects in Analyst change. Changes include renaming dimensions, adding, deleting, or renaming dimension items.

system links
In Contributor, a link that is defined by the Contributor administrator and run by a user in the Web client. This is part of the Get Data functionality in the Web client.

table-only layout
In Cognos Planning, a publish schema that consists of a table-only layout, and is particularly suitable for the Generate Framework Manager Model extension.

view layout
In Cognos Planning, a publish schema that consists of a layout of views over text values.

User Guide 797

Glossary

798 Analyst

Index
Symbols
@function, See built in functions multiple A-Table entries, 720 multiple-line entries to local A-Tables, 247 one-to-many entries to A-Tables, 721 one-to-many entries to local A-Tables, 247 owner notes to objects, 40, 43 single A-Table entries, 719 single entries to local A-Tables, 246 subheadings to reports, 145 AddLocalPreSelection macro, 651 add mode D-Links, 253 administration, 37 administration jobs definition, 791 administration links definition, 791 administration machines definition, 791 administration servers definition, 791 allocations, 235 D-Cubes, 249 allocation tables, 235, 713 adding entries, 719 adding one-to-many entries, 247 allocating entries, 722 assigning data, 237 changing entry signs, 727 changing sources and targets, 725 changing to matched descriptions, 240 Cognos package as source, 714 copying and pasting entries, 248 creating, 714 cutting subcolumn identifiers, 722 deleting, 729 deleting entries, 729 delimited ASCII files as source, 714 D-List from D-Cube as source, 714 D-Lists as source, 714 duplicate entries, 729 functional differences, 235 User Guide 799

A
access control, 45 access permissions users, 48 access rights assigning, 57, 58 controlling access, 54 default settings, 54 item-level, 60 no access setting, 54 read access, 54 setting at object level, 58 setting for libraries, 59 setting read-only globally, 60 write access, 54 access tables definition, 791 effects on Analyst - Contributor links, 284 accumulation D-links definition, 791 accumulation D-Links, 262 database D-Cubes, 262 D-Lists used, 270 execution modes, 272 one-dimensional, 271 restrictions, 264 running inversely, 274 sparse D-Cubes, 262 two-dimensional, 272 Activate macro, 651 adding A-Table entries, 719 descriptions to objects, 40, 43 dimensions to D-Cubes, 207 entries to A-Tables, 719 many-to-one entries to local A-Tables, 247

Index hiding dimension items, 726 impact of dimension item list changes, 727 importing data, 714 incomplete entries, 723 insert item buttons, 723 loading into D-Links, 240 macros, 706 maintaining, 236 managing, 725 many-to-one entries, 719 mapped ASCII files as sources, 714 menu options, 236 multiple entries, 720 new entries, 721 ODBC databases as sources, 714 one-sided entries, 723 one-to-many entries, 721 refreshing dimensions, 728 removing dimension items, 729 reordering entries, 725 saved, 248 selecting dimension items, 724 selecting source and target, 714 showing dimension items, 726 single entries, 719 three options, 235 altering dimensions effect on D-Links, 210 effect on formats, 211 alternative temporary data storage path, 218 Analyst assigning access rights, 57, 58 Cognos packages as source in D_list, 130 Cognos packages as source in D-Link, 218 registry settings, 25 restarting, 26 sample models, 28 saving data, 25 vs. spreadsheets, 28 Analyst and Microsoft Excel differences, 26 Analyst - Cognos Finance links, 285 D-Link options, 286 how they work, 286 installing, 286 when to use, 286 800 Analyst Analyst - Contributor links, 276 D-Links, 278 effects of access tables in Contributor, 284 factors affecting memory usage, 281 fill and substitute mode, 283 how they work, 278 installing Contributor Administration Console, 277 macro recommendation, 279 multiple links target same link in same cube, 278 opening links from computers without access to original data store, 282 running batches using DLinkExecuteList macro, 282 running while making model changes, 283 security, 277 selecting Contributor application, 284 when to use, 276 annotations cells, 167 printing, 790 publish, 769 annotations tables, 763 anonymous access, 51 Append mode in D-Lists, 132 applications definition, 791 ASCII files A-Table sources, 714 creating columns, 735 creating duplicate columns, 736 creating hierarchies, 136 creating overlapping columns, 736 defining columns, 734 defining columns in delimited files, 734 deleting columns or column breaks, 737 delimited, 734 delimited vs. fixed width, 734 dummy maps, 747 effects of changing, 749 effects of changing delimited files, 750 effects of changing source ASCII files for D-Links, 752 effects of changing source files for D-Links, 752 fixed width, 734 follow on option, 741 start import at row option, 731

Index assumption cube definition, 791 ATabImportCognosPackage macro, 708 ATabImportDelimitedText macro, 709 ATabImportFileMap macro, 710 ATabImportOdbc macro, 710 A-table definition, 791 A-Tables, See allocation tables ATabOpen macro, 706 ATabRefresh macro, 707 audit trails clearing, 148 printing records, 149 searching for text strings, 149 setting in D-Cubes, 148 viewing for cells within D-Cubes, 149 authentication third-party providers, 46, 57 authentication providers, 46, 51 automating model publishing, 773 automation importing from IQD files, 81 averages applying time averages, 106 applying weighted averages, 107 overriding weighted averages, 108 removing, 108 time, 106 weighted, 106 BiFs definition, 792 BiFs, See built in functions blank rows, columns, and pages suppressing, 165 blank selections D-Cubes, 194 bounce definition, 792 breakback applying holds, 151 BiFs, 320 default rules, 149 holding subtotals, 151 integer arithmetic, 152 removing holds, 151 setting global targets, 151 setting targets, 153 setting to decimal mode, 153 setting to integer mode, 153 subtotals, 151 using with D-Cubes, 149 vs. solve in spreadsheets, 151 breakback allocations drilling down, 293 built in functions, 315 breakback, 320 circularity, 319 creating, 316 Cumul, 324 customizing, 316 Cycles, 324 Days, 327 DaysOutstanding, 328 DCF, 331 Decum, 336 Delay, 337 DelayDebt, 340 DelayStock, 343 deleting, 317 DepnAnnual, 346 DepnDB, 352 DepnSLN, 355 DepnSYD, 356 Deytd, 359 Differ, 360 User Guide 801

B
basic signon run batch job via command line, 619 batch job run via command line, 619 batch jobs batch utility wizard, 619 macros, running, 626 batch utility command line publish, 621, 773 batch utility wizard, 619 best practices, 19 BiF library sample models, 31

Index Drive, 362 Drive1, 365 Drive2, 368 editing, 316 ErlangDelayAgents, 371 ErlangDelayFull, 373 ErlangDelayLite, 375 ErlangLossLite, 375 Feed, 379 FeedParam, 380 Forecast, 383 Funds, 394 FV, 395 Grow, 406 ICF, 408 input parameters, 320 Internal Rate of Return - IRR, 411 Lag, 418 Last, 421 Lease, 423 LeaseVariable, 443 library, 315 Linavg, 472 Mix, 473 Movav, Movsum, 475 MoveMed, 481 nesting, 319 Nper, 484 NPV, 493 Outlook, 498 outputs, 317 PMT, 501 printing and previewing, 40 priority of calculations, 319 Proportion, 517 PV, 509 Rate, 518 removing outputs from formulas, 318 Repeat, 529 results, 317 SeasonLite, 529 SeasonPro, 533 showing calculation errors, 320 Simul, 568 StockFlow, 571 StockFlowAF, 577 802 Analyst StockflowBQ, 582 switchover dates, 609 switchover dates in formulas, 610 switchover dates in timescale D-Lists, 610 Tier, 585 Time, 586 timescales, 120 TimeSum, 593 TMax, 601 TMin, 602 Transform, 603 TRound, 605 Ytd, 607 built-in functions glossary, 378

C
calculated target items matching, 235 calculations circularity in BiFs, 319 dates, 114 D-Lists, 93 interrupting, 148 priority, 319 showing errors, 320 canceling selections in local A-Tables, 232 capabilities, 50 Capitalization Depreciation (DepnSYD) BiF, 356 Case Sensitive option matching descriptions, 234 cell annotations editing, 167 printing, 790 removing, 168 viewing, 167 cell references, See D-List item names cells annotating, 167 copy and paste patterns, 185 holding a global range, 181 holding a range on the current page of a D-Cube, 181 holding in D-Cubes, 181 locking in D-Cubes, 182, 183

Index printing annotations, 168 releasing holds, 181 releasing holds from D-Cubes, 182 releasing holds from ranges, 181 removing locks, 183 changing ASCII files, 749 A-Tables to matched descriptions, 240 column and row widths in D-Cubes, 166 configuration settings, 40 dimension items in D-Links, 241 entry signs, 727 keyboard layout, 40 keyboard settings, 41 library access rights, 59 library details, 303 match descriptions to A-Tables, 241 maximum workspace in Analyst, 40 maximum workspace settings, 41 number of Undos and Redos, 40 optional D-Link settings, 220 order of D-Cube dimensions, 211 path of Filesys.ini, 40 position of existing subcolumns, 260 ranges of data in D-Cubes, 178 source ASCII files for D-Links, 752 sources and targets for A-Tables, 725 character matches finding, 191 CheckAccess macro, 652, 653 circularity BiFs, 319 formulas, 99 Close macro, 653 closing Analyst, 25 D-Cubes, 156 ODBC links, 40 Cognos Configuration workspace settings in Analyst, 37 Cognos Connection create a data source connection, 84 Cognos Finance - Analyst links, See Analyst - Cognos Finance links Cognos namespace, 45 Cognos packages as source in A-Table, 714 import data into Analyst, 130 source in D-Link, 218 Cognos Performance Applications creating Planning models, 72 monitoring live Planning data, 74 Cognos Series 7 namespace, 46 color conventions data in D-Cubes, 160 D-Lists, 146 column breaks deleting in ASCII files, 737 columns changing width in D-Cubes, 166 defining in ASCII files, 734 defining in file maps, 734 setting widths while printing, 785 splitting headings onto two lines, 203 transposing, 206 command line examples, 622 options, 621 run a batch job, 619 command line options importing from IQD files, 81 commands applying in D-Cubes, 175 copy and paste patterns, 185 D-Cubes, 173 Random number, 185 Redo, 165 Round, 185 Undo, 165 commentary definition, 792 conditional formulas applying, 101 assigning to D-List items, 103 configuration settings, 40 configure OS signon, 619 contributions definition, 792 Contributor Administration definition, 792 Contributor - Analyst links, 279 User Guide 803

Index Contributor - Analyst links, See Analyst - Contributor links Contributor - Contributor links, 280 control access, 54 assigning, 54 control macros, 650 converting input variables to values, 618 copying Analyst Contributor links, 280 A-Table entries, 248 data from spreadsheets to Analyst, 163 data in D-Cubes using operators, 163 D-Lists, 121 formulas, 97 Holds, Locks, and Protects, 185 into libraries, 314 macro commands, 616 objects in libraries, 307 range on the same page of a D-Cube, 161 ranges from page to page of a D-Cube, 162 copyright material printing, 20 create a data source connection, 84 creating detailed fact query subject, 88 Framework Manager projects, 86 Planning tables, 38 cubes definition, 792 Cumul (Cumulated) BiF, 324 current owners definition, 792 customizing BiFs, 316 custom menus, 34 custom timescales, 120 custom toolbar buttons creating, 36 cut-down models definition, 792 cutting subcolumn identifiers for A-Tables, 722 subcolumns in D-Links, 259 Cycles BiF, 324

D
data allocation in D-Cubes, 158 color conventions in D-Cubes, 160 editing in D-Cubes, 168 entering into D-Cubes, 159 holding in D-Cubes, 181 locking in D-Cubes, 183 protecting in D-Cubes, 183 resetting in D-Cubes, 171 database D-Cubes, 262 database object names, 758, 768 database schema publishing data, 768 database servers setting up MS SQL Server Desktop Engine, 775 datastores definition, 792 data types, 763 date allocations, D-Links, 287 dates applying formats, 117 calculations, 114 data in file maps, 738 formats, 114, 115 importing data from file maps, 738 specific format, 116 Days BiF, 327 DaysOutstanding BiF, 328 DCF (Discounted Cash Flow) BiF, 331 D-Cube Formatting, 191, 192 D-Cube allocations, 249 complex, 251 creating allocation D-Links, 249 default slices, 251 editing D-Links, 252 enabling D-Links to recognize A-Tables, 251 running allocation D-Links, 249 selecting and slicing allocation D-Cubes, 250 vs. lookup and accumulation D-Links, 250 DCubeCalculate macro, 670 DCubeClearMask macro, 671 DCubeCommand macro, 672

804 Analyst

Index DCubeCreateDSels macro, 673 DCubeCreateTSels macro, 676 D-Cube data importing into D-Lists, 137 DCubeDeleteSels macro, 678 DCubeDeselect macro, 679 DCubeExport macro, 680 DCubeIncreaseSelect macro, 683 DCubeInput macro, 684 D-Cube macros, 669 DCubeNew macro, 685 DCubeOpenChooseSel macro, 687 DCubeOpen macro, 686 DCubeOpenNamedSel macro, 688 DCubeOpenSelect macro, 689 DCubePageId macro, 690 DCubePage macro, 689 DCubePrint macro, 691 DCubeReselect macro, 693 D-Cubes, 147 adding dimensions, 207 annotating cells, 167 applying commands, 175 audit trails, 148 AutoSum, 190 breakback, 149 changing column and row widths, 166 changing ranges of data, 178 closing, 156 color conventions for data, 159 commands, 173 commands menu, 173 copy and paste patterns, 185 copying data from spreadsheets, 163 copying data using operators, 163 copying range on the same page, 161 copying ranges from page to page, 162 creating, 154 creating selections, 194 data allocation, 158 database, 262 definition, 792 deleting data, 176 deleting dimensions, 208 displaying zero values as blank cells, 193 drilling down, 290 editing, 161 editing cell annotation, 167 editing data, 168 editing saved selections, 200 editing selections, 199 edting a range of data on the current page, 176 entering data, 159 expanded selections, 193 expanding subtotals, 157 exporting data, 186 exporting data to spreadsheets, 190 filling with data using one-off internal D-Links, 287 finding character matches, 191 finding text, 191 format priority in cells, 155 formatting, 110, 191 formatting data prior to export, 189 formulas used in, 28 global formats, 109 holding cells, 181 holding global ranges of cells, 181 holding ranges of cells on current page, 181 importing data using ODBC links, 299 interrupting calculations, 148 limited selections, 154 loading saved selections, 198 local vs.global formats, 191 locking cells, 183 locking data, 183 locking formula cells, 182 macros, 669 managing, 203 memory management, 202 navigating, 212 opening, 156 opening multiple cubes, 157 order of D-List selection, 154 previewing, 786 previewing summary information, 787 printing, 788 printing cell annotations, 168 protecting data, 183 protecting formula cells, 182 publishing, 755 Random number command, 185 recovering from errors, 165, 172 User Guide 805

Index releasing holds from individual cells, 181 releasing holds from ranges of cells, 181 removing cell annotation, 168 removing numerical sorts, 205 reordering dimensions, 211 reselecting, 207 reselecting items after changing data, 194 resetting data, 171 resetting structure, 206 revealing blank rows and columns, 166 revealing zero suppressed rows and columns, 166 rounding, 185 saved selections, 193 saved selections and D-Links, 197 saving, 213 saving selections, 197 searching for text, 191 selecting a range of cells, 170 selections, 193 separating totals from detail items, 164 setting columns or rows to zero, 177 showing details only, 203 showing formulas only, 203 showing full selection, 207 size limitations, 147 slicing, 157, 205 sorting rows and columns, 204 sparse, 262 splitting column headings onto two lines, 203 substituting D-Lists, 209 substituting D-Lists used by several D-Cubes, 209 suppressing blank rows, columns, and pages, 165 suppressing zero rows, columns, and pages, 165 target area, 253 transposing rows and columns, 206 viewing cell annotation, 167 viewing formulas, 161 viewing multiple slices, 157 viewing pages, 213 viewing slices, 212 virtual dimensions, 230 DCubeSort macro, 694 DCubeTranspose macro, 695 DCubeUpdate macro, 696 decimal mode setting, 153 806 Analyst Decum BiF, 336 default access settings, 54 default masks, 62 default rules breakback, 149 default slices allocation D-Cubes, 251 defining column breaks in delimited ASCII files, 734 columns in ASCII files, 734 columns in file maps, 734 unique parts of D-List items, 141 Delay BiF, 337 DelayDebt BiF, 340 Delay macro, 653 DelayStock BiF, 343 deleting A-Table entries, 729 BiFs, 317 column breaks in ASCII files, 737 data from D-Cubes, 176 dimensions from D-Cubes, 208 D-Lists, 139 entire A-Tables, 729 entries in A-Tables, 244, 729 individual entries in A-Tables, 729 items from D-Lists, 131 libraries, 303 namespaces, 47 objects using the library, 304 delimited ASCII files, 734 A-Table sources, 714 defining column breaks, 734 effects of changing, 750 dependants showing, 140, 306 DepnAnnual (Depreciation Annual) BiF, 346 DepnDB (Depreciation Diminishing Balance) BiF, 352 DepnSLN (Straight Line Depreciation) BiF, 355 DepnSYD (Sum of Year Digits Depreciation) BiF, 356 Depreciation Sum of Year Digits (DepnSYD) BiF, 356 descriptions adding to objects, 40, 43 showing, 307 detail cells viewing origins, 161

Index detailed fact query subject, 88 detail items separating from totals, 164 details printing and previewing for D-Lists, 786 Deytd (Original Series Year to Date) BiF, 359 Differ (Difference) BiF, 360 differences between Analyst and Microsoft Excel, 26 dimensionformats table, 766 dimension for publish, 755 dimension items changing in D-Links, 241 removing, 729 selecting in A-Tables, 724 dimensions, 230 adding to D-Cubes, 207 definition, 793 deleting from D-Cubes, 208 effect on D-Links when altered, 210 reordering in D-Cubes, 211 displaying average of cells in ranges, 190 library names, 303 maximum of cells in ranges, 190 minimum of cells in ranges, 190 numbers of cells in ranges, 190 sum of cells in ranges, 190 zero values as blank cells, 193 DLinkActivateQueue macro, 663 DLinkExecSel macro, 664 DLinkExecuteList macro, 666 running batches of D-Links, 282 DLinkExecutelnv macro, 663 DLinkExecute macro, 665 D-Link macros, 662 DLinkNew macro, 667 DLinkOpen macro, 668 D-Links, 215 accumulation, 270 add mode, 253 Analyst - Cognos Finance, 285 Analyst - Contributor, 276 Case Sensitive option, 234 changing dimension items, 241 changing optional settings, 220 copying data in D-Cubes from page to page, 288 creating, 217 creating match descriptions pairings, 233 cutting subcolumns, 259 date allocations, 287 dealing with unassigned records, 254 definition, 793 dimensions, 230 dimensions and D-Lists, 216, 230 dumping items, 256 dump options, 254 effects when dimensions are altered, 210 empty selections, 230, 232 enabling to recognize A-Tables, 251 exchanging source and target D-Lists, 228 execution modes, 252 filling D-Cubes with data using one-off internal D-Links, 287 fill mode, 253 inverse, 227 loading A-Tables, 240 local allocation tables, 242 lookup, 264 lookup and accumulation, 262 Lookup D-Links, 266 macros, 662 matching calculated target items, 235 matching descriptions, 233 naming, 220 one-off D-Links, 286 opening, 220 pairing source and target dimensions, 219 recognizing A-Tables, 251 rounding data, 257 running, 222 saving, 220 scaling data, 257 selecting items, 232 selecting required items from unpaired dimensions, 219 selecting sources and targets, 217 setting scaling and rounding, 258 subcolumns, 259 substitute mode, 253 subtract mode, 253 target area, 253 troubleshooting, 294 User Guide 807

Index unpaired dimensions, 231 unpaired source dimensions, 231 unpaired target dimensions, 231 unvisited dimensions, 230 using with saved selections, 197 virtual dimensions, 230 DLinkSelectList macro, 668 D-List format definition, 793 DListItemCopyFromDList macro, 635 DListItemImportCognosPackage macro, 632 DListItemImportDCube macro, 644 DListItemImportDelimitedText macro, 637 DListItemImportFileMap macro, 640 DListItemImportFinance macro, 642 DListItemImportIQD macro, 645 DListItemImportODBC macro, 646 D-List item names, 91 D-List macros, 627 DListNew macro, 627 DListOpen macro, 628 D-Lists, 91 applying conditional formulas, 101 applying date formats, 117 applying formats, 117 applying free-text format to items, 118 applying local formats, 109 applying logical formulas, 101 applying numeric formats, 112 applying time formats, 117 assigning local formats, 110 Blank if Zero option, 193 calculation, 93 changing how data displays, 112 color conventions, 146 controlling appearance of items, 109 copying, 121 copying formulas, 97 creating, 91 creating formulas using formatted text, 103 creating import links, 124, 131 creating subtotals, 95 creating timescales, 119 custom timescale, 120 date formats, 114 defining unique parts of items, 141 808 Analyst definition, 793 deleting, 139 deleting items, 131 editing, 121 editing formulas, 97 editing item names, 123 editing summary information, 144 entering formulas, 95 entering prefixes, 192 entering suffixes, 192 export as e.List, 131 finding underlying numbers in formatted cells, 111 forcing to zero, 108 format attribute screen, 109 formats, 117 formatted items in formulas, 103 formatting specific rows or columns, 111 formula errors, 98 formulas, 28, 93 from D-Cube as source in an A-Tables, 714 hierarchical sorting, 135 implementing changes, 131 importing D-Cube Data, 137 importing D-List items into D-Lists using ODBC, 298 importing formulas, 93 importing items from Cognos package, 130 importing items from D-Cubes, 128 importing items from mapped ASCII files, 127 importing items from other D-Lists, 125 importing items from unmapped ASCII files, 126 importing items using ODBC, 129 importing using IQDs, 67 import modes, 132 inserting items, 123 loading local formats, 110 macros, 627 managing, 139 moving, 139 numeric formats, 112 opening, 91 pasting items from spreadsheets databases or word processors, 125 positioning new objects, 135 previewing details, 786 previewing formulas, 95, 786

Index previewing when building D-Cubes, 154 printing, 788 printing details, 786 printing formulas, 95, 786 publishing, 755 removing formulas, 98 renaming, 139 reordering in D-Cubes, 211 reordering items, 142 running import links, 124 saving local formats, 110 scaling factor, 113 searching for, 140 selecting formats, 109 selection order when creating D-Cubes, 154 setting colors, 146 setting up switchovere dates in timescales, 610 showing dependants, 140 showing precedents, 140 sorting items, 143 source in A-Tables, 714 substituting when used by several D-Cubes, 209 substituting within D-Cubes, 209 time averages, 106 time formats, 114 timescale, 118 updating items, 124, 131 validating, 39 viewing formulas, 100 viewing summary information, 144 DListUpdate macro, 629 DOS file names revealing, 307 double counting in formulas, 99 drill down definition, 793 drilling down, 290 breakback allocations, 293 cells using source or mapped ASCII files, 291 data assigned to dump items, 257 data imported from ASCII files using follow on, 747 data in D-Cubes, 290 error messages, 295 how it works, 291 one cell using D-Cube as source, 291 ranges of cells, 292 troubleshooting, 294 viewing origins of detail cells in D-Cubes, 161 Drive (Driver Many Forcasts) BiF, 362 Drive1 (Driver 1 Forcast) BiF, 365 Drive2 (Driver 2 Forcasts) BiF, 368 DSNs creating for database servers, 773 dummy maps, 747 creating, 747 dump items D-Links, 256 drilling down to assigned data, 257 used with dump options, 257 dump options D-Links, 254 dump items used, 257 duplicate columns creating in ASCII files, 736 duplicate entries A-Tables, 729 removing, 729 duplicate target items subcolumns, 261 duplicating libraries, 313

E
e.Lists definition, 793 export D-List as e.List, 131 importing from Performance Applications, 67 in Analyst, 131 editing allocation D-Cube D-Links, 252 BiFs, 316 cell annotation, 167 data in D-Cube cells using operators, 169 D-Cubes, 161, 168 D-List item names, 123 D-Lists, 121 formulas, 97 local A-Table entries, 246 message fields in macros, 619 objects in libraries, 308 range of data on the current page of a D-Cube, 176 saved selections, 200 User Guide 809

Index selections, 199 unique names, 141 editor macros, 615 editors definition, 793 empty selections, 232 D-Links, 230 End Method, 571 entries reordering in A-Tables, 725 entry signs changing, 727 ErlangDelayAgents BiF, 371 ErlangDelayFull BiF, 373 ErlangDelayLite BiF, 375 ErlangLossLite BiF, 375 errors circularity in formulas, 99 common in timescale D-Lists, 120 double counting in formulas, 99 formula omissions, 98 recovering, 165 eTrust SiteMinder namespace, 46 Everyone group, 53 examples command line, 622 exchanging source and target D-Lists by running D-Links inversely, 228 execution modes, 252 accumulation D-Links, 272 D-Links, 252 lookup D-Links, 266 expanded selections D-Cubes, 193 expanding subtotals in D-Cubes, 157 exporting data from D-Cubes, 186 D-List as e.List, 131 text strings, 737 export tables, 762 ExportToEList macro, 629 extensions definition, 793 810 Analyst external namespaces Cognos Series 7, 46 eTrust SiteMinder, 46 LDAP, 46 Microsoft Active Directory, 46 NTLM, 46 SAP, 46

F
Feed BiF, 379 FeedParam (Feed Parameter) BiF, 380 file maps, 731 creating, 731 creating columns in ASCII files, 735 creating duplicate columns in ASCII files, 736 creating overlapping columns in ASCII files, 736 date data, 738 defining columns, 734 definition, 794 deleting columns or column breaks in ASCII files, 737 delimited ASCII files, 734 delimited vs. fixed width files, 734 dummy maps, 747 follow on, 741 importing data, 738, 740 importing text and date data, 738 macros, 704 text data, 738, 740 Use Row as Column Names option, 731 using LIB parameter, 733 files delimited, 734 fixed width, 734 IQD, 68 filesys.ini, 38 changing path, 40 security, 54 FileTranslate macro, 653 file types IQDs, 67 filling a D-Cube with data using a one-off internal D-Link, 287 fill mode D-Links, 253

Index Filters importing from SAP BW, 88 finding character matches, 191 IID in a formatted cell, 111 text strings, 191 finding information, 20 fixed width files vs. delimited files, 734 fixed width ASCII files, 734 creating columns, 735 creating duplicate columns, 736 creating overlapping columns, 736 effects of changing, 752 FMapNew macro, 705 FMapOpen macro, 705 follow on option ASCII files, 741 drilling down, 747 overlapping subheadings, 745 subheadings, 745 font style and size setting while printing, 785 forcing to zero D-List items, 108 Forecast BiF, 383 format attribute screen, 109 format priorities D-Cube cells, 155 formats, 109 applying D-List formats, 117 applying local formats to D-Lists, 109 applying numeric formats, 112 assigning, 110 date, 114 D-Lists, 109, 117 effects when dimensions are altered, 211 global vs. local, 109 loading saved formats, 191 numeric, 112 removing global D-Cube formats, 191 saving, 192 selecting, 109 time, 114 formatting D-Cube data prior to export, 189 D-Cubes, 191 specific rows or columns, 111 formula cells locking in D-Cubes, 182 formulas, 93 applying conditional formulas, 101 applying logical formulas, 101 cell references,, 28 checking integrity, 309 circularity, 99 copying, 97 creating using D-List formatted text, 103 D-List formatted items, 103, 111 D-Lists, 28, 93 double counting, 99 editing, 97 entering into D-Lists, 95 errors, 98 line returns, 93 omissions, 98 previewing, 786 prewiewing in D-Lists, 95 printing and previewing, 786 printing in D-Lists, 95 priorities, 104 removing, 98 setting priorities, 105 setting up switchover dates in BiFs, 610 showing in D-Cubes, 203 spaces, 93 tabs, 93 targeting items, 241 viewing in D-Cubes, 161 viewing in D-Lists, 100 viewing priorities, 104 See D-List item names formulas (CalcTexts) importing, 93 Framework Manager creating and publishing a Framework Manager package, 87 creating a project and import metadata, 86 IQD files for importing into D-Lists, 68 Framework Manager Models creating, 779 updating, 780 User Guide 811

Index free-text format applying to D-List items, 118 functional differences between allocation options, 235 Funds BiF, 394 FV (Future Value) BiF, 395 hierarchies, 759 importing D-Lists, 69 hierarchy tables, 760 highlighting unused objects in libraries, 307 hold definition, 794 holding cells in D-Cubes, 181 data in D-Cubes, 181 global range of cells, 181 range of cells on the current page of a D-Cube, 181 holds applying against breakback, 151 breakback, 151 breakback on subtotals, 151 releasing from D-Cubes, 182 releasing from individual cells in D-Cubes, 181 releasing from ranges, 181 subtotals, 151

G
generate Framework Manager model wizard, 776 Generate Transformer Model macro, 697 generate Transformer Model wizard, 780 Get Data definition, 794 Global Customer Services Web site, 20 global formats comparing to local formats, 109 D-Cubes, 191 loading saved formats, 191 removing, 191 saving, 192 global targets setting using breakback, 151 glossary Erlang built-in functions, 378 go to production definition, 794 Great Outdoors Analyst, 29 grids definition, 794 groups, 47 security, 57 Grow BiF, 406 GUID definition, 794

I
ICF (Inflated Cash Flow) BiF, 408 identifiers cutting subcolumns in A-Tables, 722 IID finding using Summary Info button, 580 import blocks definition, 794 Import from IQD wizard changes in the data source, 71 data sources, 70 deployment options, 71 hierarchies, 69 Performance Applications, 67 importing data from file maps, 738 data into A-Tables, 714 date data from file maps, 738 D-Cube data, 137 D-List items from Cognos package, 130 D-List items from D-Cubes, 128 D-List items from mapped ASCII files, 127 D-List items from unmapped ASCII files, 126 D-List items into D-Lists using ODBC, 298 D-List items using ODBC, 129

H
help getting, 20 hiding dimension items in A-Tables, 726 items within a D-List, 40 hierarchical sorting creating hierarchies from ASCII files, 136 D-Lists, 135 multiple independent hierarchies, 136 simple hierarchies, 135

812 Analyst

Index formulas (CalcTexts), 93 items from other D-Lists, 125 local A-Tables, 243 modes in D-Lists, 132 SAP BW data, 88 text data from file maps, 740 importing D-Lists changes in the source database, 71 mapping table, 69 importing from IQD files automation, 81 command line options, 81 importing from Performance Applications mandatory fields, 74 import links creating, 124, 131 definition, 794 running, 124 Impromptu Query Definition, 68 incomplete entries A-Tables, 723 incorporating new D-List items, 135 incremental publish, 757 index files rebuilding, 39 information finding, 20 input parameters BiFs, 320 input variables converting to values, 618 inserting into macro commands, 618 inserting D-List items, 123 information using system parameters, 28 input variables into macro commands, 618 lines to separate totals from detail items, 164 multiple steps in macros, 617 insert items buttons A-Tables, 723 installing ODBC driver, 297 integer arithmetic breakback, 152 integer mode setting, 153 integrity checking, 309 interrupting calculations, 148 inverse D-Links, 227 exchanging source and target D-Lists, 228 running, 227 IQD files, 68 importing D-Lists and e.Lists, 67 mandatory fields, 74 IRR (Internal Rate of Return) BiF, 411 ItemDelete macro, 630 item identification numbers (IID), 103 finding in D-List formatted cells, 111 finding with Summary Info button, 103 viewing, 785 ItemImport macros DListItemImportIQD, 645 DListItemImportODBC, 646 Item Import macros, 631 DListItemCopyFromDList, 635 DListItemImportDCube, 644 DListItemImportDelimitedText, 637 Item Import Macros DListItemImportCognosPackage, 632 item-level access rights, 60 item-level security using masks, 61 item list changes impact on A-Tables, 727 item names, See D-List item names items tables, 758

J
job servers definition, 794

K
Keep mode in D-Lists, 132 keyboard layout changing, 40 keyboard settings changing, 41

User Guide 813

Index

L
Lag BiF, 418 Last BiF, 421 LDAP namespace, 46 Lease BiF, 423 LeaseVariable BiF, 443 LibCopy macro, 654 LIB parameter using with file maps, 733 libraries administration, 302 BiF, 315 changing access rights, 59 changing details, 303 checking for missing objects, 309 checking integrity, 309 copying objects, 307 creating, 302, 312 default access settings, 54 definition, 795 deleting, 303 deleting objects, 304 displaying names, 303 duplicating, 313 editing objects, 308 highlighting unused objects, 307 Library Copy wizard, 310 Library window, 304 locating built in functions, 40 locating ODBC sources, 40 moving objects to different libraries, 305 opening objects, 310 print all security information, 302 print change library path, 302 printing lists of objects, 789 print security information, 302 print security information for selected item, 302 probables, 309 renaming objects, 304 replacing, 314 required sets of objects, 309 revealing DOS file names, 307 running batches of D-Links, 225 selecting objects using Library Copy wizard, 312 showing dependants, 306

showing object descriptions, 307 showing precedents, 305 suspects, 309 library names running macros from, 623 library number running macros from, 622 limited selections D-Cubes, 154 Linavg (Linnear Average) BiF, 472 line returns in formulas, 93 loading A-Tables into D-Links, 240 global formats in D-Cubes, 191 local formats, 110 saved selections, 198 local allocation tables, 242 changing dimension items in D-Links, 241 creating pairings, 242 deleting, 729 deleting entries, 244 editing entries, 246 importing, 243 many-to-one entries, 247 multiple-line entries, 247 navigating, 238 reordering lines, 246 saving as saved A-Tables, 243 single entries, 246 targeting formula items, 241 using D-Cube data, 250 using wildcards, 244 local formats, 109 assigning, 110 D-Cubes, 191 formatging specific rows or columns, 111 loading, 110 saving, 110 local links definition, 795 locating built in functions, 40 locating ODBC sources, 40 lock definition, 795 Lock command using to write-protect cells, 183

814 Analyst

Index locked cells unlocking, 183 locking cells in D-Cubes, 183 cells using Lock command, 183 data in D-Cubes, 183 formula cells in D-Cubes, 182 locks removing from cells in D-Cubes, 183 logical formulas applying, 101 lookup d-links definition, 795 lookup D-Links, 262 creating, 266 database D-Cubes, 262 D-Lists used, 269 execution modes, 266 one-dimensional, 265 restrictions, 264 running inversely, 266 sparse D-Cubes, 262 two-dimensional, 265 unpaired dimensions, 266 copying and pasting commands, 616 DCubeCalculate, 670 DCubeClearMask, 671 DCubeCommand, 672 DCubeCreateDSels, 673 DCubeCreateTSels, 676 DCubeDeleteSels, 678 DCubeDeselect, 679 DCubeExport, 680 DCubeIncreaseSelect, 683 DCubeInput, 684 DCubeNew, 685 DCubeOpen, 686 DCubeOpenChooseSel, 687 DCubeOpenNamedSel, 688 DCubeOpenSelect, 689 DCubePage, 689 DCubePageId, 690 DCubePrint, 691 DCubeReselect, 693 D-Cubes, 669 DCubeSort, 694 DCubeTranspose, 695 DCubeUpdate, 696 definition, 795 Delay, 653 DLinkActivateQueue, 663 DLinkExecSel, 664 DLinkExecute, 665 DLinkExecuteList, 666 DLinkExecutelnv, 663 DLinkNew, 667 DLinkOpen, 668 D-Links, 662 DLinkSelectList, 668 DListImportIQD, 645 DListItemCopyFromDList, 635 DListItemImportCognosPackage, 632 DListItemImportDCube, 644 DListItemImportDelimitedText, 637 DListItemImportFileMap, 640 DListItemImportFinance, 642 DListItemImportODBC, 646 DListNew, 627 DListOpen, 628 D-Lists, 627 User Guide 815

M
MacroExecute macro, 655, 704 macros, 613 Activate, 651 AddLocalPreSelection, 651 ATab ImportCognosPackage, 708 ATabImportDelimitedText, 709 ATabImportFileMap, 710 ATabImportOdbc, 710 A-Tables, 706 ATabOpen, 706 ATabRefresh, 707 CheckAccess, 652 CheckAccessLevel, 653 Close, 653 codes, 615 command line update D-List from IQD, 623 command line update IQD mapping table, 624 command line upgrade D-List, 625 control, 650 converting input variables to values, 618

Index DListUpdate, 629 editing message fields, 619 editor, 615 ExportToEList, 629 file maps, 704 FileTranslate, 653 FMapNew, 705 FMapOpen, 705 Generate Transformer Model, 697 inserting input variables, 618 inserting multiple steps, 617 ItemDelete, 630 Item Import, 631 LibCopy, 654 MacroExecute, 655, 704 Message, 656 ODBC, 650 ODBCClose, 650 ODBCConnect, 650 PackDir, 656 PackDirSel, 657 printing nested macros, 619 Publish, 698 recording, 615 RefreshDataWarehouse, 649 Rem, 658 Reset, 658 Run, 658 running, 615 running a batch job, 626 running batches of D-Links, 227 running from a library name, 623 running from a library number, 622 Save, 660 ShutDown, 660 SliceCommand, 699 SliceUpdate, 700 TestData, 660 tracing, 617 transcripts, 614 UnPackDir, 661 variables, 617 maintaining allocation tables, 236 hierarchies, 135 manually reordering D-List items, 142 816 Analyst many-to-one entries A-Tables, 719 local A-Tables, 247 mapped files ASCII file as A-Table sources, 714 mapping table Import from IQD wizard, 69 masks, 40 applying item-level security, 61 creating, 61 customizing, 40 default, 62 managing, 40 public, 62 match descriptions definition, 795 matching descriptions allocating A-Table entries, 722 case sensitive option, 234 changing to A-Tables, 241 creating pairings, 233 D-Links, 233 duplicate target items, 261 match all, 722 match detail, 722 match first, 722 matching calculated target items, 235 Maximum Value (Tmax) BiF, 601 maximum workspace changing in Analyst, 40 changing settings, 41 definition, 795 Max Supply, 575 memory considerations when running D-Links, 226 management, 40 management in D-Cubes, 202 running low message, 40 menus custom, 34 message fields editing in macros, 619 Message macro, 656 metadata publish tables, 770 tables, 763

Index Microsoft Active Directory, 46 Microsoft ODBC for Oracle servers creating DSNs, 773 Microsoft SQL Server 2000 Desktop Engine setting up as a database server, 775 Microsoft SQL servers creating DSNs, 773 Minimum Value (Tmin) BiF, 602 Min Supply, 575 Mix BiF, 473 models automating publishing, 773 changes that impact publish tables, 783 creating from Performance Applications, 72 definition, 795 Great Outdoors Analyst, 29 samples, 28 slice update, 31 tutorialgo, 29 updating using D-Cube update links, 288 working with samples, 28 Movavg (Moving Average) BiF, 475 MoveMed BiF, 481 moving D-Lists, 139 objects to different libraries, 305 Movsum (Moving Sum) BiF, 475 multiple column source files, 137 multiple D-Cubes opening, 157 multiple entries A-Tables, 720 multiple independent hierarchies, 136 multiple-line entries local A-Tables, 247 multiple links target same link in same cube, 278 multiple steps inserting in macros, 617 multiple users writing to the same object simultaneously, 28 restoring, 47 See Also authentication providers naming D-Links, 220 navigating D-Cubes, 212 local A-Tables, 238 open D-Cubes, 157 nested macros printing, 619, 789 nesting BiFs, 319 new entries A-Tables, 721 no access assigning, 57 Nothing to transfer message, 294 Nper (Number of Periods) BiF, 484 NPV (Net Present Value) BiF, 493 NTLM namespace, 46 numerical sorts removing, 205 numeric formats applying, 112 D-Lists, 112

O
object-level setting access rights, 58 objects, 43 adding descriptions, 40 copying in libraries, 307 deleting, 304 moving to different libraries, 305 opening in libraries, 310 printing to .csv files, 790 renaming using the library, 304 revealing names from DOS filenames, 43 showing dependants, 306 showing descriptions, 307 showing precedents, 305 unused, 307 ODBC, 297 macros, 650 ODBCClose macro, 650 ODBCConnect macro, 650 User Guide 817

N
namespaces, 45 definition, 795 deleting, 47 multiple, 46

Index ODBC databases A-Table sources, 714 ODBC links, 297 closing, 40 creating, 297 importing data into D-Cubes, 299 importing D-List Items into D-Lists, 298 installing ODBC driver, 297 setting up ODBC data source, 298 offline grids definition, 796 omissions in formulas checking, 98 one-dimensional accumulation D-Links, 271 lookup D-Links, 265 one-off D-Links, 286 one-sided entries A-Tables, 723 one-to-many entries adding to local A-Tables, 247 A-Tables, 721 opening Analyst, 25 D-Cubes, 156 D-Links, 220 D-Lists, 91 multiple D-Cubes, 157 objects in libraries, 310 operators using to copy D-Cube data, 163 using to edit data in D-Cube cells, 169 optional settings changing in D-Links, 220 options command line, 621 Oracle creating Microsoft drivers, 774 Oracle servers creating DSNs, 773 order D-List selection when creating D-Cubes, 154 orientation printing, 785 Original Series Year to Date (Deytd) BiF, 359 origins viewing for detail cells, 161 OS signon configure for batch utility wizard, 619 run batch job via command line, 619 Outlook BiF, 498 Outlook Method, 575 outputs BiFs, 317 removing BiF outputs from formulas, 318 overlapping columns creating in ASCII files, 736 overlapping subheadings follow on, 745 overriding weighted averages, 108 owner notes adding to objects, 40, 43 owners definition, 796

P
P_APPLICATIONCOLUMN table, 764 P_APPLICATIONOBJECT table, 764 PackDir macro, 656 PackDirSel macro, 657 pages viewing, 213 parameters command line, 621 passwords managing, 60 pasting A-Table entries, 248 items from databases, 125 items from spreadsheets, 125 items from word processors, 125 path of Filesys.ini changing, 40 Performance Applications importing D-Lists after changes, 71 mandatory fields, 74 periods of uneven length timescales, 120 planners definition, 796

818 Analyst

Index planning sample models, 28 Planning Contributor Users, 49 Planning Rights Administrator, 49 Planning tables creating, 38 PMT (Payment) BiF, 501 positioning new objects in D-Lists, 135 PowerCubes creating, 782 precalculated summaries, 776 precedents showing, 140, 305 prefixes classifying object names, 768 column names prefixed with data types option, 768 entering, 192 previewing, 786 D-Cubes, 786 D-Cube summary information, 787 details of D-Lists, 786 D-Lists when building D-Cubes, 154 formulas in D-Lists, 95, 786 printing, 785 all security information for library, 302 annotations, 168 audit trail records, 149 BiF specifications, 40 cell annotations, 790 D-Cubes, 788 D-Lists, 788 formulas and details of D-Lists, 786 formulas in D-Lists, 95 library security information, 302 lists of objects in libraries, 789 nested macros, 619, 789 objects to .csv files, 790 orientation, 785 security information for selected item in a library, 302 setting column widths, 785 setting fonts, 785 setting up, 785 printing copyright material, 20 priorities calculations, 319 formula, 105 product application definition, 796 Proportion BiF, 517 protect definition, 796 protecting cells from breakback, 151 data, 183 formula cells in D-Cubes, 182 items within a D-List, 40 providers security, 46 public masks, 62 publish containers definition, 796 publishing, 755 alternative migration paths, 775 automating model publishing, 768 command line, 773 creating DSNs for database servers, 773 creating Microsoft SQL DSNs, 773 creating Oracle DSNs, 773 database schema, 768 D-Cubes, 755 definition, 796 D-Lists, 755 Generate Framework Manager Model wizard, 776 generate Transformer Model wizard, 780 setting up MS SQL Server Desktop Engine, 775 understanding incremental publish, 757 Publish macro, 698 publishoptions table, 765 PV (Present Value) BiF, 509

R
Random number command, 185 ranges changing in D-Cubes, 178 copying from page to page of a D-Cube, 162 copying on the same page of a D-Cube, 161 editing on the current page of a D-Cube, 176 selecting in D-Cubes, 170 Rate BiF, 518 User Guide 819

Index read-only access, 54 assigning, 54 setting globally, 60 setting to active objects, 59 read-only mode multiple users writing to the same object simultaneously, 28 rebuilding index files, 39 recommendation for Analyst to Contributor links, 279 reconciliation definition, 796 recording macros, 615 recovering from errors, 165, 172 Redos, 165 changing number, 40 references refreshing, 39 RefreshDataWarehouse macro, 649 refreshing A-Table dimensions, 728 references, 39 registry settings for Analyst, 25 related documentation, 19 releasing holds from cells in D-Cubes, 181 Rem macro, 658 Remove Obsolete mode in D-Lists, 132 removing BiF outputs from formulas, 318 cell annotation, 168 dimension items, 729 duplicate A-Table entries, 729 formulas, 98 global formats from D-Cubes, 191 holds against breakback, 151 library access rights, 59 locks from cells in D-Cubes, 183 numerical sorts, 205 removing averages, 108 renaming D-Lists, 139 objects using the library, 304 reordering dimensions in D-Cubes, 211 D-List items, 142 entries in A-Tables, 725 820 Analyst lines in local A-Tables, 246 Repeat BiF, 529 replacing libraries, 314 reporting directly from publish tables, 775 reports adding subheadings, 145 reselecting D-Cube items after changing data, 194 D-Cubes, 207 Reset macro, 658 resetting data in D-Cubes, 171 D-Cube structure, 206 restarting Analyst, 26 restoring namespaces, 47 Restricted D-Cube Access, 57 restrictions lookup and accumulation D-Links, 264 results BiFs, 317 revealing blank rows and columns, 166 DOS file names, 307 object names from DOS filenames, 43 zero suppressed rows and columns, 166 reviewers definition, 797 rights definition, 797 roles, 47 security, 57 rollups, 768 rounding D-Cube cells, 185 D-Link data, 257 solving errors using breakback in integer mode, 152 Rounding Method (TRound) BiF, 605 rows changing width in D-Cubes, 166 transposing, 206 Run macro, 658 running batches of D-Links using library functions, 225 batches of D-Links using macros, 227

Index D-Cube allocation D-Links, 249 D-Links, 222 D-Links in Manager, 266 D-Links using open D-Cubes as targets, 223 D-Links using specific D-Cubes as sources, 223 D-Links using specific D-Cubes as targets, 223 D-Links while making model changes, 283 D-Links with source D-Cubes open, 224 D-Links with target D-Cubes open, 223 import links into D-Lists, 124 inverse D-Links, 227 lookup D-Links inversely, 266 macros, 615 open D-Links, 223 update links in D-Cubes, 225 setting scaling, 258 scaling factor D-Lists, 113 scaling formats D-Lists, 112 scenario dimensions, 775 searching D-Lists, 140 text strings in audit records, 149 SeasonLite BiF, 529 SeasonPro BiF, 533 security access control, 45 Analyst - Contributor links, 277 assigning access, 57, 58 control access, 54 default access settings, 54 filesys.ini, 54 manage masks, 60 managing passwords, 60 masks, 60 no access, 54 printing library security information, 302 providers, 46 read access, 54 third-party authentication, 46, 57 users, groups, and roles, 57 write access, 54 security overview, 50 selecting allocation D-Cubes, 250 Contributor application for Analyst - Contributor links, 284 dimension items in A-Tables, 724 formats, 109 items for D-Links, 232 libraries using Library Copy wizard, 310 objects using Library Copy wizard, 312 range of cells in a D-Cube, 170 required items from unpaired dimensions, 219 source and target for A-Tables, 714 selections canceling in local A-Tables, 232 creating from D-Cubes, 194 D-Cubes, 193 editing, 199, 200 User Guide 821

S
sample models, 28 samples BiF library, 31 Great Outdoors Analyst, 29 slice update, 31 working with samples, 28 SAP BW importing data, 88 SAP namespace, 46 saved allocation tables, 248 saved selections D-Cubes, 193 definition, 797 editing, 200 loading, 198 using in A-Table allocations, 250 using with D-Links, 197 Save macro, 660 saving Analyst data, 25 D-Cubes, 213 D-Links, 220 formats, 192 global formats applied to D-Cubes, 192 local A-Tables as saved A-Tables, 243 local format, 110 selections, 197 scaling D-Link data, 257 scaling factors, 257

Index expanded, 193 reselecting D-Cubes, 207 saving, 197 showing details only, 203 showing formulas only, 203 showing full D-Cube selection, 207 setting access rights at object level, 58 alternative migration paths for large applications, 775 audit trails in D-Cubes, 148 Blank if Zero option, 193 breakback to integer or decimal mode, 153 columns to zero in D-Cubes, 177 column widths while printing, 785 D-List colors, 146 fonts while printing, 785 formula priorities, 105 global targets using breakback, 151 ODBC data sources, 298, 299 printing options, 785 read-only access globally, 60 read-only access to active objects, 59 rows to zero in D-Cubes, 177 scaling factor within D-Lists, 113 switchover dates in BiF formulas, 610 switchover dates in timescale D-Lists, 610 targets using breakback, 153 settings configuration, 40 showing calculation errors, 320 dependants, 306 details only, 203 dimension items in A-Tables, 726 D-Lists dependants, 140 D-Lists precedents, 140 formulas only, 203 full D-Cube selection, 207 object descriptions, 307 precedents, 305 ShutDown macro, 660 simple hierarchies, 135 Simul BiF, 568 single entries adding to A-Tables, 719 822 Analyst local A-Tables, 246 size limitations D-Cubes, 147 SliceCommand macro, 699 slices viewing, 212 viewing multiple slices, 157 SliceUpdate macro, 700 Slice Update sample, 31 slicing allocation D-Cubes, 250 D-Cubes, 157, 205 solving rounding errors using breakback in integer mode, 152 sorting D-Cube rows and columns, 204 D-List items, 143 sources changing, 725 selecting for A-Tables, 714 spaces in formulas, 93 sparse D-Cubes, 262 splitting column headings onto two lines, 203 spreadsheets copying data to Analyst, 163 vs. Analyst, 28 StockFlowAF BiF, 577 StockFlow BiF, 571 StockflowBQ BiF, 582 Straight Line Depreciation (DepnSLN) BiF, 355 structure resetting for D-Cubes, 206 subcolumns changing position, 260 clearing, 261 cutting in D-Links, 259 D-Links, 259 duplicate target items, 261 subheadings adding to reports, 145 substitute mode D-Links, 253 substituting D-Lists used by several D-Cubes, 209 D-Lists within D-Cubes, 209

Index subtotals breakback on hold, 151 creating, 95 expanding in D-Cubes, 157 modifying formulas in D-Lists, 135 subtract mode D-Links, 253 suffixes entering, 192 summary information editing in D-Lists, 144 finding IID, 103, 111 previewing for D-Cubes, 787 viewing in D-Lists, 144 Sum of Year Digits Depreciation (DepnSYD) BiF, 356 suppressing blank rows, columns, and pages, 165 zero rows, columns, and pages, 165 switchover dates BiFs, 609 setting up in BiF formulas, 610 setting up in timescale D-Lists, 610 synchronize definition, 797 system administrator, 45 system links definition, 797 system parameters Analyst, 28 setting using breakback, 153 TestData macro, 660 text finding, 191 text data file maps, 738 importing from file maps, 738 text qualifiers exporting text strings, 737 special cases, 738 Tier BiF, 585 time averages applying, 106 D-Lists, 106 removing, 108 Time BiF, 586 time formats, 114, 116 applying, 117 specific, 116 timescales BiFs, 120 common errors, 120 creating, 119 custom, 120 D-Lists, 118 periods of uneven length, 120 switchover dates, 609, 610 time averages, 106 TimeSum BiF, 593 TMax (Maximum Value) BiF, 601 TMin (Minimum Value) BiF, 602 toolbar menu creating custom toolbar buttons, 36 totals separating from detail items, 164 tracing macros, 617 transcripts viewing, 614 Transform BiF, 603 Transformer Model, 780 transposing rows and columns, 206 troubleshooting D-Links, 294 drilling down, 294 error messages appear when drilling down, 295 nothing happens when drilling down, 294 Nothing to transfer message, 294 User Guide 823

T
table-only layouts definition, 797 table-only publish layout, 757, 766 tabs formulas, 93 target area D-Cubes and D-Links, 253 targeting formula items, 241 target items duplicates in subcolumns, 261 targets changing, 725 selecting for A-Tables, 714 setting global targets, 151

Index TRound (Rounding Method) BiF, 605 tutorialgo sample model, 29 two-dimensional accumulation D-Links, 272 creating, 272 two-dimensional lookup D-Links, 265 creating, 266 using custom menus, 34 saved selections in A-Table allocations, 250

V
validating D-Lists, 39 variables macros, 617 version dimensions, 775 viewing audit trails for cells within D-Cubes, 149 cell annotation, 167 formula priorities, 104 formulas, 100 formulas in D-Cubes, 161 IID, 785 multiple slices D-Cubes, 157 origins of detail cells, 161 pages, 213 slices, 212 transcripts, 614 view layout definition, 797 view publish layout, 768, 771 views, 771 virtual dimensions, 230

U
understanding Analyst, 26 understanding incremental publish, 757 Undo command, 165 undos changing number, 40 uneven length timescale periods, 120 unique codes defining unique parts of D-List items, 141 unique names editing, 141 unlocking cells, 183 unmapped ASCII files importing items, 126 UnPackDir macro, 661 unpaired dimensions, 231 lookup D-Links, 266 selecting required items, 219 source, 231 target, 231 unregistering namespaces, 47 unused objects highlighting, 307 unvisited dimensions D-Links, 230 update links running in a single D-Cube, 225 Update mode in D-Lists, 132 updating D-List items, 124, 131 models using D-Cube update links, 288 upgrade pipe symbols, 141 users, 47 classes and permissions, 48 security, 57 setting library access rights, 59 824 Analyst

W
weighted averages applying, 107 D-Lists, 106 overriding, 108 removing, 108 wildcard characters using in local A-Tables, 244 wizards Import from IQD wizard, 67 working with samples, 28 workspace changing maximum in Analyst, 40 D-Cubes, 40 workspace settings using Cognos Configuration, 37 write-access, 54 assigning, 54

Index multiple users writing to the same object simultaneously, 28 write-protect using Lock command, 183

Y
Ytd (Year to Date) BiF, 607

Z
zero values displaying as blank cells in D-Cubes, 193

User Guide 825