COGNOS(R) 8

FRAMEWORK MANAGER

USER GUIDE

Framework Manager User Guide 01-08-2005 Framework Manager 8.1

Cognos(R) 8 Business Intelligence Readme Framework Manager User Guide USER GUIDE

THE NEXT LEVEL OF PERFORMANCE

TM

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

Copyright
Copyright (C) 2005 Cognos Incorporated. Portions of Cognos(R) 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. 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 11 Chapter 1: Framework Manager 13 Planning Your Metadata 13 Objects You Will Work With 14 The Project Page 15 The Project Viewer 15 The Explorer Tab 18 The Diagram Tab 18 The Dimension Map Tab 18 The Properties Pane 19 The Summary Pane 19 The Search Pane 19 Naming Conventions for Objects in a Project 19 Sample Models 20 The Great Outdoors Data Warehouse Model 20 The Great Outdoors Sales Model 21 The Great Outdoors Sales and Retailers Model 21 Chapter 2: Designing a Project 23 Project Files 23 Create a Project 24 Open a Project 25 Upgrading Models from Previous Versions of ReportNet 25 Verify the Model in Your Existing ReportNet Environment 27 Upgrade the Model in Framework Manager 27 Verifying the Upgraded Model 27 Model for Analysis Studio 28 Use Separate Namespaces 28 Importing Metadata 28 Import from a Relational Database 29 Import from an SAP BW Data Source 30 Import from a Cognos 8 Model 32 Import from an Architect Model or an Impromptu Catalog 32 Import from DecisionStream or Cognos 8 Data Manager 32 Import From a Third-party Metadata Source 35 Import Using XML as a Data Source 38 Use a Project with Multiple Data Sets 38 Export Metadata 39 Setting Up a Multilingual Reporting Environment 40 Modeling with Multilingual Data Sources 41 Multiuser Modeling 42 Setting Up Your Multiuser Modeling Environment 42 Segmenting and Linking Recommendations 43 Create a Segment 43 Create a Link 44 Managing Projects 45 Copy a Project 45 Move a Project 46 Rename a Project 46 User Guide 3

Delete a Project 46 Create Model Documentation 47 Search for Objects in the Model 47 Repository Control 48 Creating Repository Connections 48 Add a New Project to a Repository 50 Add an Existing Project to a Repository 50 Create a Local Project From a Repository 50 Check In and Check Out a Project 50 Get the Latest Version 51 View History 51 Recording Transactions in Log Files 52 View Transaction History 52 Play Back Transactions From a Log File 52 Running Action Logs in Batch Mode 53 Synchronize Projects 55 Fixing Errors Caused by Invalid Objects 57 Chapter 3: Data Sources 59 Working With Data Source Connections 59 Types of Data Source Connections 61 Cognos Cubes 62 Native Metadata 62 XML Data Sources 63 Microsoft SQL Server and Microsoft Analysis Services 63 ODBC Data Sources 64 Composite Software 64 Create a Data Source Connection 64 Recommendation - Use Network Paths for File-Based Data Sources 66 Modifying Data Source Properties 67 Example - Moving a Relational Model from One Environment to Another 67 Specify Where Aggregate Rollups are Processed 68 Improve Performance by Setting Query Processing Type 69 Using Functions to Create Expressions 69 Select Function Sets 69 Quality of Service 70 Chapter 4: Preparing Relational Metadata for Use in Reports 73 Verifying Relationships 73 Cardinality 74 Modify a Relationship 76 Create a Relationship 77 Create a Relationship Shortcut 77 Detect and Generate Relationships 78 Working with Dimensions 78 Create a Regular Dimension 79 Specify Roles 83 Create a Measure Dimension 84 Convert a Measure into a Query Item 85 Define Scope Relationships 85 Create a Regular Dimension Based on Existing Objects 85 Explore Dimensions 86 Test a Dimension, Query Subject, or Query Set 86 Modify Multiple Objects at Once 88 Convert a Regular Dimension into a Query Subject 88 Working with Query Subjects 89 Relational Data Source Query Subjects 89 Model Query Subjects 89 4 Framework Manager

Stored Procedure Query Subjects 90 Create a Query Subject 90 Modifying a Query Subject 91 Add Items to the Query Subject 91 Specify a Determinant 92 Modify a Stored Procedure Query Subject 94 Example - Use Prompts with a Stored Procedure 95 Create a Model Query Subject Based on Existing Objects 95 Explore Query Subjects 96 Create a Query Set 96 Test a Query Subject, Query Set, or Dimension 98 Modify Multiple Objects at Once 100 Validate a Query Subject 100 Update Query Subjects 101 Convert a Query Subject into a Dimension 101 Edit the SQL 102 Change the Type of SQL 102 Change How the SQL Is Generated 106 Supporting Multilingual Metadata 107 Using a Macro to Model Multilingual Data 108 Add a Language to a Project 108 Export a Translation Table 109 Import a Translation Table 109 Example - Create a Multilingual Project for Relational Metadata 110 Modifying the Properties of Query Items 111 Modifying How Query Items Are Aggregated 113 Format Query Items 117 Define a Prompt Control 118 Convert a Query Item into a Measure 119 Modify Multiple Objects at Once 119 Adding Business Rules 120 Create a Calculation 120 Create a Filter 122 Applying a Filter 123 Example - Create and Apply a Filter to Relational Metadata 124 Using Prompt Values to Filter Data 125 Create a Parameter Map 125 Example - Specifying a Language Value for Relational Metadata 127 Example - Moving a Relational Model from One Environment to Another 127 Create a Session Parameter 128 Using Parameters with Relational Data Source Query Subjects 129 Creating Prompts with Query Macros 129 Organizing the Model 136 Create a Star Schema Group 137 Use Shortcuts 140 Create a Folder or Namespace 141 Create a Query Item Folder 142 Create a Measure Folder 142 Chapter 5: Preparing SAP BW Metadata for Use in Reports 143 Mapping SAP BW Objects to Framework Manager 143 Working with Dimensions 144 Modify a Regular Dimension 145 Specify Roles 149 Modify a Key Figures Dimension 150 Conform SAP BW Dimensions 151 Remove a Conformed SAP BW Dimension 152

User Guide 5

Explore Dimensions 152 Test a Dimension, Query Subject, or Query Set 152 Modify Multiple Objects at Once 154 Working with Model Query Subjects 155 Create a Model Query Subject 155 Create a Model Query Subject Based on Existing Objects 156 Explore Query Subjects 156 Create a Query Set 157 Test a Query Subject, Query Set, or Dimension 159 Modify Multiple Objects at Once 161 Validate a Model Query Subject 161 Supporting Multilingual Metadata 161 Use a Macro to Define SAP BW Currency 162 Add a Language to a Project 162 Export a Translation Table 163 Import a Translation Table 163 Example - Create a Multilingual Project for SAP BW Metadata 164 Modifying the Properties of Query Items 164 Modifying How Query Items Are Aggregated 166 Format Query Items 169 Define a Prompt Control 170 Modify Multiple Objects at Once 171 Adding Business Rules 171 Create a Calculation 172 Create a Filter 174 Applying a Filter 175 Using Prompt Values to Filter Data 176 Create a Parameter Map 183 Create a Session Parameter 184 Organizing the Model 185 Use Shortcuts 185 Create a Folder or Namespace 186 Create a Query Item Folder 186 Create a Measure Folder 187 Optimizing SAP BW Performance 187 Dimension Settings 187 Outer Join Governor Setting 189 Data Source Settings 189 Settings in the Report Authoring Tools 190 Chapter 6: Making Metadata Available to Report Authors 191 Verify a Model 191 Set Governors 194 Improving Performance by Reusing Cached Data When Running a Report 196 Create or Modify a Package 197 Controlling Access to Metadata and Data 199 Add a User, Group, or Role 199 Add Data Security 200 Add or Remove Object Security 202 Add Package Security 203 Explore a Package 204 View the Distribution of an Object in Packages 204 Specify Languages 204 Externalizing Query Subjects and Dimensions 205 Publish a Package 207 Publish a Package Based on an OLAP Data Source 208 Analyze the Effects of Changes to a Package 208

Framework Manager

Chapter 7: Guidelines for Modeling Metadata 211 Scenarios 211 New Objects in Cognos 8 211 Determinants 212 Regular Dimension 212 Measure Dimension 212 Scope Relationship 213 Dimensional Modeling of Relational Data Sources 213 Checking Imported Metadata 213 Simplifying the Model Using Dimensional Concepts 216 Resolving Ambiguous Relationships 218 Defining Dimensions and Determinants 222 Creating Star Schema Groups 228 Upgrading a Best Practices Model from ReportNet 1.x 229 Reviewing the Existing Model 230 Upgrading the Model 230 Chapter 8: The SQL Generated by Cognos 8 237 Understanding Dimensional Queries When Using Best Practices 237 Single Fact Query 237 Multiple-fact, Multiple-grain Query on Conformed Dimensions 238 Modeling 1-n Relationships as 1-1 Relationships 240 Multiple-fact, Multiple-grain Query on Non-Conformed Dimensions 241 Resolving Ambiguously Identified Dimensions and Facts 244 Resolving Queries That Should Not Have Been Split 244 Resolving Queries That Are Split in the Wrong Place 247 Appendix A: Troubleshooting 253 Expression Syntax for Different Languages 253 Long Time to Process an SAP BW Query 253 Unable to View the Result Set of a Stored Procedure 253 Data Query Stored Procedure Updates the Data Source 253 Unable to Execute Stored Procedures Imported from ERWin Metadata Source 254 Unable to Use Preview and Security Filters with Stored Procedure Query Subjects 254 Unable to Use an IQD Created in Framework Manager That Contains an Oracle Stored Procedure 254 Cannot Test a Query Subject Imported from a Third-party Data Source 254 Script Error Occurs When Testing Query Subjects 255 Unable to Validate a Calculation if SQL Was Invalid Earlier 255 Joins That Contradict Index and Key Information 255 Security Error Messages in Windows 2003 Server Edition 255 Required Currency Not Shown 255 Unable to Find Functions List for Vendor 256 Expressions Imported from Business Objects Metadata Source Do Not Work 256 Invalid Role-Based Packages after Upgrading a Model 256 FDS Error Occurs When Using Vendor Specific Functions 256 Columns With the BIT Datatype Are Summarized in Query Studio Reports 257 Error With Some Graphic Items 257 Errors Creating Expressions Containing Vendor Specific Functions 257 Relationships Involving Table Views Are Not Imported from an Oracle Designer File 257 SQL View Definitions Are Not Imported from a Power Designer File 257 Undoing Repairs Does Not Reset Prompt Values 258 Appendix B: Using the Expression Editor 259 Operators 259 Summaries 264 Constants 274 Constructs 275

User Guide 7

Business Date/Time Functions 276 Block Functions 279 Macro Functions 280 Common Functions 282 A-C 282 D-G 286 H-L 287 H-L 288 M-Q 290 R-Z 293 DB2 295 DB2 Cast 303 DB2 Math 304 DB2 Trigonometry 305 Informix 306 Informix Math 309 Informix Trigonometry 309 MS Access 310 MS Access Cast 314 MS Access Math 315 MS Access Trigonometry 315 Oracle 316 Oracle Cast 321 Oracle Math 321 Oracle Trigonometry 321 Red Brick 323 SQL Server 326 SQL Server Cast 329 SQL Server Math 329 SQL Server Trigonometry 330 Teradata 331 Teradata Trigonometry 334 SAP BW 336 SAP BW OLAP 336 SAP BW Trigonometry 336 SAP BW Math 337 Sybase 338 Sybase Math 341 Sybase Trigonometry 342 Member Summaries 343 Appendix C: Data Formatting Reference 347 Data Formatting Properties 347 Calendar Type 347 Clock 347 Currency 347 Currency Display 347 Currency Symbol 347 Currency Symbol Position 347 Date Ordering 348 Date Separator 348 Date Style 348 Decimal Separator 348 Display AM / PM Symbols 348 Display As Exponent 348 Display Days 348 Display Eras 348

Framework Manager

Display Hours 348 Display Milliseconds 348 Display Minutes 349 Display Months 349 Display Months 349 Display Seconds 349 Display Time Zone 349 Display Weekdays 349 Display Years 349 Display Years 349 Exponent Symbol 349 Group Size (digits) 349 International Currency Symbol 349 Mantissa (digits) 350 Maximum No. of Digits 350 Minimum No. of Digits 350 Missing Value Characters 350 Negative Pattern 350 Negative Sign Position 350 Negative Sign Symbol 350 No. of Decimal Places 350 Padding Character 350 Pattern 350 Percentage Symbol 351 Percent Scale (integer) 351 Scale 351 Secondary Group Size (digits) 351 Thousands Separator 351 Time Separator 351 Time Style 351 Time Unit 351 Use Thousands Separator 351 Zero Value Characters 352 Appendix D: Using Patterns to Format Data 353 Date and Time Symbols 354 Decimal Format Symbols 360 All Locales 360 Appendix E: Guidelines for Externalizing SAP BW Dimensions 361 SAP BW Query Requirements 362 Framework Manager Considerations 363 Building PowerCubes from SAP BW Data 364 Appendix F: Reserved Words 367 Appendix G: XML Data Types 373 Glossary 375 Index 379

User Guide 9

10

Framework Manager

Introduction
Framework Manager is a metadata modeling tool. A model is a business presentation of the information in one or more data sources. When you add security and multilingual capabilities to this business presentation, one model can serve the needs of many groups of users around the globe. To use Framework Manager, you should understand data modeling and how to write queries. This document includes the procedures, examples, notes, tips, and other background information to help you create a project prepare a model for reporting create and publish a package For more information about using this product, visit the Cognos support Web site (http://support.cognos.com). For information about education and training, click the Training link from this site. The following documents contain related information, and may be referred to in this document. Note that the availability of the studios described in these documents depends on your licensing permissions. To change your licensing permissions, see your administrator. Document Cognos 8 Installation and Configuration Guide Cognos 8 Administration and Security Guide Query Studio User Guide Report Studio User Guide Event Studio User Guide Description Installing, upgrading, configuring, and testing Cognos 8, changing application servers, and setting up samples Managing servers, security, reports, and Portal Services; setting up Cognos samples; and customizing Cognos 8 Creating ad hoc business intelligence reports Authoring reports that analyze corporate data according to specific needs Creating and managing agents that monitor data and perform tasks when the data meets predefined thresholds Exploring, analyzing, and comparing dimensional data Migrating Cognos Series 7 applications for use in Cognos 8 Business Intelligence Migrating Cognos Series 7 applications for use in Cognos 8 Business Intelligence

Analysis Studio User Guide Architect Metadata Migration User Guide Impromptu Catalog and Report Migration User Guide

This document is available as online help and as an online book. From within the online help, you can click the following link to open a printable version of this document (PDF). Our documentation includes user guides, tutorial guides, reference books, and other materials to meet the needs of our varied audience. User Guide 11

Introduction

Online Help
All information is available in online help. Online help is available from the help button in a Web browser, or the Help menu and help button in Windows products. You can also download the online help from the Cognos support Web site (http://support.cognos.com).

Books for Printing

The information in each online help system is available in online book format (PDF). However, the information from a given help system may be divided into more than one online book. Use online books when you want to print a document or when you want to search the whole document. 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 format, solely for the purpose of providing internal training on, operating, and maintaining the Cognos software. Online books are available from the introduction to the online help for each component. All online books are available on the Cognos documentation CD. You can also read the product readme files and the installation guides directly from Cognos product CDs.

12

Framework Manager

Chapter 1: Framework Manager

Framework Manager is a metadata modeling tool. A model is a business presentation of the information in one or more data sources. When you add security and multilingual capabilities to this business presentation, one model can serve the reporting, ad hoc querying, and analysis needs of many groups of users around the globe. Before you do anything in Framework Manager, we recommend that you thoroughly plan the metadata that your organization needs for its reports (p. 13). To get started with Framework Manager, you should understand the objects you work with in Framework Manager (p. 14). As well, sample models are included with Framework Manager for you to explore (p. 20).

Planning Your Metadata

Before you do anything in Framework Manager, we recommend that you thoroughly plan the metadata that your organization needs for its reports. Then you should review the names of data sources, tables, and columns in your data source to ensure that you are not using names reserved by Cognos 8. If you must use a reserved word, enclose the word in quotes in the SQL specification. For example, select Orderdate, "Timezone". For more information, see "Reserved Words" (p. 367).

Analyze the Problem

Before you start, you must understand the reporting problem that you are trying to solve, and what data is available to solve it. If you cannot address questions such as the following, talk to your users about their reporting requirements. Do you and the report authors agree on the reporting requirements? Issues to resolve can include multilingualism, performance, security, and how to organize and combine query items and filters. Does the data source contain the data and metadata that you need? Without metadata such as primary keys, indexes, and foreign keys, your reports may take too long to run, or may produce incorrect results. If the data source does not contain the data and metadata that you need, will it be changed, or will you work around it? Does the same data exist in more than one source? If so, choose the data source that most closely fits your reporting requirements. If a data warehouse is available, it is typically a better choice than an operational database. A data warehouse based on a star schema is ideal. If this does not exist, and you expect that your reporting application will be heavily used, consider arranging for one to be created. Which data source tables are the fact tables, which are the dimensions, and which are both fact table and dimension? What are the keys and attributes of each dimension? Which relationships are required? Do any required tables contain embedded dimension information other than foreign keys? Are there multiple relationship paths between tables? If so, what does each path represent? You must define the preferred path for each. Framework Manager makes it easy to handle simple changes such as renaming, reorganizing, and enhancing the metadata to meet your reporting requirements.

User Guide 13

Chapter 1: Framework Manager

Objects You Will Work With

When you work in Framework Manager, you work in a project. A project contains a model, namespaces, packages, and data sources. A model is the metadata layer that you import from one or more data sources. The model provides a business presentation of the metadata. After you define a Framework Manager project and namespace, you can publish one or more packages containing metadata information to the Cognos 8 server. Then your users can create reports and queries in the report authoring tools.

Projects
A project is a set of models, packages, and related information for maintaining and sharing model information. A single project can span many data sources or tables.

Models
A model is the set of related dimensions, query subjects, and other objects required for one or more related reporting applications. The Framework Manager model is a metadata layer that adds value to a data source in several ways. Most importantly, it provides a business view of the information in the source data to report authors and query users to simplify building reports and queries. The business view can organize data items in folders that represent business areas for reporting format data items using numeric, currency, date, time, and other formats present multilingual folder and item names, descriptions, tips, and data so that users can operate in their language of choice automate the generation of SQL queries sent to the relational data source specify default prompting This can include having Cognos 8 prompt the user using a descriptive name while actually filtering on a code or key value for improved query performance. In particular, you can modify the Framework Manager model to ensure that queries sent to the data source are efficient, well formed, and secure. You can specify the rules governing query generation, restrict user access to specific rows or columns of data, and model data relationships to hide the complexity of data from report authors.

Namespaces
A namespace uniquely identifies query items, dimensions, query subjects, and other objects (p. 28). You import different databases into separate namespaces to avoid duplicate names.

Packages
A package is a subset of the dimensions, query subjects, and other objects defined in the project (p. 197). A package is what is actually published to the Cognos 8 server, and it is used to create reports and ad hoc queries.

Dimensions
A dimension is a broad grouping of descriptive data about a major aspect of a business, such as products, dates, or markets. The types of dimensions that you can work with in Framework Manager are regular dimensions and measure dimensions. In SAP BW, measure dimensions are called key figures. Each regular dimension consists of one or more hierarchies that typically contain several levels.

Query Subjects
A query subject is a set of query items that have an inherent relationship. In most cases, query subjects behave like tables. Query subjects produce the same set of rows regardless of which columns were queried.

14

Framework Manager

Chapter 1: Framework Manager There are different types of query subjects: data source, model, and stored procedure. A data source query subject directly references data in a single data source. When metadata is first imported, a data source query subject is created by default for each table that you select. Default relationships between query subjects are created for you automatically. You can refine data source query subjects in various ways. For example, you can add calculations or filters, or you can add or modify relationships between query subjects to define the query generation rules for report authors. A single Framework Manager project can contain data source query subjects from one or more data sources not necessarily of the same type. This provides heterogeneous database access. The data source columns and calculations returned by the SQL query are referred to as query items. Model query subjects can contain query items from any number of data source query subjects. Model query subjects can be enhanced by adding filters or calculations to create additional query items. You can also use query subjects from other model query subjects. The stored procedure query subject operates much like a data source query subject in that it defines a set of query items that are available to the model from the underlying data source. Stored procedure query subjects cannot be enhanced by filters or calculations.

Query Items
A query item is the smallest piece of the model that can be placed in a report. It represents a single characteristic of something, such as the date that a product was introduced. Query items are contained in query subjects or dimensions. For example, a query subject that references an entire table contains query items that represent each column in the table. For report authors, query items are the most important objects for creating reports. The properties of query items are what report authors use to build the reports that they want.

The Project Page

After you create (p. 24) or open a project (p. 25), the project page appears. The project page is the environment in which you design, package, and publish project metadata. This page contains several panes and views that you can use to view and modify the objects in a project.

The Project Viewer

The Project Viewer shows the objects in a project in a hierarchical view. You can use the Project Viewer to view, modify, and create these objects: dimensions (p. 78) query subjects (p. 89) data sources (p. 28) namespaces (p. 28) parameter maps (p. 125) folders (p. 141) segments (p. 43) links (p. 44) calculations (p. 120) filters (p. 122) packages (p. 197) Relationships and imported functions are shown in both the Diagram and Explorer tabs.

User Guide 15

Chapter 1: Framework Manager The Project Viewer uses the following icons to represent objects and states. A project may use some or all of the icons. Icon Description Represents the project. Represents the root namespace or any other namespace in the project. Represents the data source folder. Represents a data source. Represents the parameter map folder. Represents a parameter map. Represents the packages folder. Represents a package. Represents a dimension. Represents a hierarchy.

Represents a level in a hierarchy.

Represents a measure dimension. Represents a measure. Represents a query subject. Represents an invalid query subject. Represents a query subject based on multidimensional data. Represents an invalid query subject based on multidimensional data. Represents a query subject that contains query items whose Usage property is set to Fact. Represents an invalid query subject that contains query items whose Usage property is set to Fact.

16

Framework Manager

Chapter 1: Framework Manager

Icon

Description Represents a query item. Represents a calculation whose Usage property is set to Attribute. Represents a calculation whose Usage property is set to Identifier. Represents an embedded calculation. Represents an invalid embedded calculation. Represents a calculation whose Usage property set to Fact. Represents an invalid embedded filter. Represents a query item whose Usage property is set to Identifier. Represents a query item whose Usage property is set to Fact. Represents a query item that is located under a shortcut query subject. Represents a calculation. Represents an invalid calculation. Represents a filter. Represents an invalid filter. Represents a relationship. Represents an invalid relationship. Indicates that the object is checked into the repository. Indicates that the object is checked out of the repository. Indicates that the object is checked out of the repository by a different user. Indicates a published package.

User Guide 17

Chapter 1: Framework Manager

Icon

Description Indicates that a linked segment or project was updated. Indicates that the object is a dimension. This icon appears on top of other icons. Indicates that the object is linked. This icon appears on top of other icons. Indicates that the object is a shortcut. This icon appears on top of other icons.

For more information about correcting invalid objects, see "Verify a Model" (p. 191).

The Explorer Tab

The Explorer tab shows the contents of a project, similar to any file system. Objects can be arranged by name, class, or description. If you have a large number of objects in a project, it may be easier to locate them in the Explorer tab. You can use the Explorer tab to view, create, and modify objects and relationships. You can also create folders and namespaces to group objects.

The Diagram Tab

The Diagram tab uses a diagram to show the relationships between objects in a project. Relationships between objects are shown as lines with cardinality notation (p. 75). You can expand objects and namespaces to show the object hierarchy and the relationships between objects. You can use the Diagram tab to view, create, and modify objects and relationships. You can also create folders and namespaces to group objects. In the Diagram tab, you can also organize objects Tip: From the Diagram menu, click Auto Layout. focus on an object Tip: Click an object and, from the Diagram menu, click Set Focal Point. find an object Tip: Right-click an object in the Project Viewer and click Locate in Diagram.

The Dimension Map Tab

You can use the Dimension Map tab to view, create, and modify hierarchies and levels for the dimension you selected in the Project Viewer. You can also view and modify scope relationships. The Measures and Attributes tabs appear after you click the Dimension Map tab. Use the Measures tab to view all the measures that are available in the model. Use the Attributes tab to view or modify the role of the select query item. You can also embed calculations in the query item. Tip: The best way to view SAP BW metadata is in the star layout. From the Diagram menu, click Auto Layout Diagram, and then select star.

18

Framework Manager

Chapter 1: Framework Manager

The Properties Pane

The Properties pane shows the properties of the objects that you last selected in the Project Viewer, Explorer tab, Diagram tab, Dimension Map tab, Search pane, or Summary pane. Object properties are set during import, and some property values can be modified during modeling. You can use the Properties pane to add, modify, or delete the properties of objects. You can modify the properties for multiple objects at one time. If you select more than one object, Framework Manager shows only the properties that are common to all the objects. You can sort property values by double-clicking the property heading An arrow appears to indicate the direction in which values are sorted. Tip: You can toggle between ascending and descending order. filter property values by clicking the arrow to the right of the property heading Tip: You can either click a value, or click Custom to define the criteria for the rows that you want to view. apply a property value to multiple objects by clicking the arrow next to the property and dragging the highlighted area over the properties to which you want to apply that value resize the width of the rows and columns by right-clicking the object name in the property pane

The Summary Pane

The Summary pane shows the language, statistics, and tasks available for an object that you selected in the Project Viewer. The Project section shows the design language and the active language. You can change the active language. The Statistics section shows the number of objects, by class, located in the currently selected object. If the selected object contains a folder, the contents of the folder are included in the number count. Selected objects include projects, namespaces, and folders. The default selected object is the project. The Tasks section shows actions that are applicable to the currently selected object, based on the object class. If you select a folder, actions for the folder are listed. If you select an object in that folder, the list includes actions for the object as well as for the folder. For more information about the object classes, see the c8_location\templates\bmt\CR1Model\BMTModelSpecification.xsd file.

The Search Pane

When you are working with a large project, it can be difficult to locate the objects that you need to complete a task. Use the Search pane to quickly find objects by applying different search criteria. You can either search for the object name alone, or add additional criteria, such as the location, class, a condition, or a property.

Naming Conventions for Objects in a Project

All objects in a project must have a unique way to identify them. The reference can consist of one, two, or three parts, depending upon the type of object. The parts include an object name a location in the project hierarchy, as expressed in the default language of the project. Note: If you want two dimensions or query subjects to have the same name in a project, they must be in different namespaces.

User Guide 19

Chapter 1: Framework Manager

Two-part Identifiers
Some objects in a project have a two-part identifier consisting of the name of the containing namespace and the name of the object. The object name must be unique in the containing namespace (p. 28). These objects have a two-part identifier: regular dimensions measure dimensions query subjects shortcuts to query subjects For example, a GoSales namespace contains a query subject named Product. The Product query subject has the following name, where the square brackets and periods are the syntax that Framework Manager uses for object identifiers:
[Go Sales].[Product]

One-part Identifiers
Some objects in a project have a one-part identifier. The one-part identifier must be unique across the entire project, even if the namespace contains other namespaces. These objects have a one-part identifier: namespaces functions shortcuts to namespaces shortcuts to folders

Three-part Identifiers
Some objects in a project have a three-part identifier based on the identifier of the containing query subject. Each name must be unique in the containing query subject. These objects have a three-part identifier: measures query items query item folders For example, a GoSales namespace contains a query subject named Product, and a query item named Product Code. The Product Code query item has the following name, where the square brackets and periods are the syntax Framework Manager uses for object identifiers:
[Go Sales].[Product].[Product Code]

Sample Models
Several sample models are included with Framework Manager for you to explore. In each sample model, the query items have default formatting defined. Names and descriptions were translated into many different languages. By using the Language_lookup parameter map, each user automatically sees folder and item names and descriptions in their preferred language. In addition to the following sample models, there is the Great Outdoors Company model. This is simply a data source connection to the Great Outdoors cube.

The Great Outdoors Data Warehouse Model

This model contains financial information and human resources information for the fictional company, The Great Outdoors. The model accesses a dimensional relational data source. This sample model is located in c8_location\webcontent\samples\models\go_data_warehouse. The sample model contains these views: Import view Contains the dimensions, facts, and query subjects that were imported from the data source. Dimension view 20 Framework Manager

Chapter 1: Framework Manager Contains regular dimensions and measure dimensions that were created in Framework Manager. Business view Contains model query subjects, shortcuts, and filters organized into namespaces. The namespaces appear as folders to your users. This organization of information into relevant business categories helps users to locate the information that they require.

The Great Outdoors Sales Model

This model contains sales analysis information for the fictional company, The Great Outdoors. The model accesses two relational data sources representing a transactional system. This sample model is located in c8_location\webcontent\samples\models\gosales. The sample model contains these views: Database view Contains the query subjects that were imported from the data source. Model query subjects were added to improve dimensional modeling. Fact tables were modified to create foreign keys that reference a time dimension. Dimension view Contains regular dimensions and measure dimensions that were created in Framework Manager. Business view Contains model query subjects and shortcuts organized into namespaces. The namespaces appear as folders to your users. This organization of information into relevant business categories helps users to locate the information that they require.

The Great Outdoors Sales and Retailers Model

This model contains sales analysis information and retailer information for the fictional company, The Great Outdoors. The model accesses two relational data sources representing a transactional system. This sample model is located in c8_location\webcontent\samples\models\gosales. The sample model contains one view named Database view that contains the query subjects imported from the data sources. It also contains query subjects and filters that were created in Framework Manager.

User Guide 21

Chapter 1: Framework Manager

22

Framework Manager

Chapter 2: Designing a Project

A project is a set of models, packages, and related information for maintaining and sharing model information. You design a project in Framework Manager to organize the metadata and data you want, in a format that is meaningful to report authors. When you design a project, consider how to organize it according to business needs. This includes deciding what information to share and reuse and how to do so. You can create segments (p. 43), or extend a project to other users by linking to other projects (p. 44). One way of organizing your project is to create namespaces (p. 28) to allow duplicate query subjects or query items in a project. After you design your project, you can add and modify objects to better reflect your business and prepare for reporting (p. 73). You can also use Framework Manager for multiuser modeling (p. 42). To design a Framework Manager project, do the following: Create a new project (p. 24).

Open an existing project (p. 25). Import metadata from one or more data sources (p. 28). Set up project management (p. 45).

Project Files
When you work in Framework Manager, you work in the context of a project. The Framework Manager project contains objects that you organize for reporting authors according to the business model and business rules of your organization. You view these objects in the project page (p. 15). A Framework Manager project appears as a folder that contains a project file (.cpf) and the specific .xml files that define the project. The files in a project folder are unique to each project. The project folder also contains a subfolder containing the action logs for the project. For more information, see "Recording Transactions in Log Files" (p. 52). Tip: The project and its associated files are contained in a project folder. We do not recommend adding secondary files to the project folder because they may be affected by actions such as move, rename, and delete commands on the Manage Projects menu. If you decide to add secondary files to the project folders, the files are added with absolute paths. If they are moved from the original location, they must be retargeted. These are the contents of a project folder. File name <project name>.cpf model.xml preferences.xml customdata.xml Description The Framework Manager project file, which references the .xsd and .xml files used to define a project The actual model data created by Framework Manager users The preferences for Framework Manager projects The stored diagram information, such as the diagram layout, notation, font, and color

User Guide 23

Chapter 2: Designing a Project

File name repository.xml

Description The logged version history for each project or segment that was added to a repository. This file exists only if you added projects to a repository.

Create a Project
Before you can import metadata, you must create a project. For information about using the contents of a repository to create a new project, see "Create a Local Project From a Repository" (p. 50) For information about creating a project segment, see "Create a Segment" (p. 43).

Steps
1. From the Welcome page, click Create a new project. Tip: If you are in Framework Manager, click New Project from the File menu. 2. In the New Project page, specify a name and location for the project. 3. You can add the new project to a source control repository: Click Repository, and then select the Add to repository check box. In the Connection box, click the repository connection. If you do not have a repository connection defined, you are prompted to create one. For more information, see "Creating Repository Connections" (p. 48). In the Location in Repository box, browse to a location to add the project and click Select. 4. Click OK. 5. In the Select Language page, click the design language for the project. You cannot change the language you select after you click OK, but you can add others. For information about project languages, see "Add a Language to a Project" (p. 108). 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. 6. Click OK to select the design language. The Metadata Wizard appears. 7. Choose whether to import your metadata now or later: To import now, select the import source and click Next. To delay importing metadata, click Cancel. 8. If you chose to import the metadata now, follow the instructions in the Metadata Wizard: Select a data source connection and click Next. If the data source connection you want is not listed, you must first create it (p. 64). Select the check boxes for the objects you want to import. 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. 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. Specify the criteria to use to create relationships and click Import. For more information, see "Verifying Relationships" (p. 73). Import statistics showing a list of objects that could not be imported and a count of objects that were imported are shown. 9. Click Finish.

24

Framework Manager

Chapter 2: Designing a Project 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.

Open a Project
You must open a project before you can import metadata or make changes to existing metadata. If the project was created using a model schema that is older than the currently supported version, you are prompted to upgrade the model. If you upgrade a segmented model, you must open and upgrade each segment individually. After each segment is upgraded, you can then upgrade the top level projects. If you upgrade your model, we recommend that you verify the model (p. 191) before making changes in the new environment.

Steps
1. In the Welcome page, click Open a project. 2. Browse to locate the project folder and click the .cpf file. 3. If you want to open a project directly from a source control repository, do the following: Click Repository. In the Connection box, click the repository connection. In the Project file in repository box, locate the project that you want to add and click OK. In the Create the project in the following location box, browse to the folder location for the project and click OK. For information about connecting to a new repository, see "Creating Repository Connections" (p. 48). 4. Click OK. You may be prompted to upgrade the model.

Upgrading Models from Previous Versions of ReportNet

A model that was created in a previous version of ReportNet must be upgraded before it can be dimensionally modeled. When an entire ReportNet system is upgraded to Cognos 8, an attempt is made to upgrade existing models using the information provided. If a model cannot upgrade successfully, reports using the model will not run. You must open the model in Framework Manager, upgrade it manually and republish it. Cognos 8 provides access to many data sources and enables dimensional modeling of relational data sources. For more information about new features in Cognos 8, see Cognos 8 New Features. For information about upgrading your ReportNet system to Cognos 8, see the Installation and Configuration Guide. For information about dimensional modeling of relational data sources, see "Working with Dimensions" (p. 78).

Models Based on Relational Metadata

Query subjects with level and hierarchy properties are not upgraded to dimensions. The query subject remains the same after the upgrade. In ReportNet, key and index properties existed but were not exposed to the modeler in Framework Manager. In Cognos 8, key and index information is used to create determinants but they are not exposed to the user.

User Guide 25

Chapter 2: Designing a Project Query subjects containing key and index properties or dimensional information are not converted to determinants during the upgrade. When the model is verified after the upgrade, these query subjects are flagged as needing repair. For information about handling issues reported while verifying a model, see "Repairing Upgraded Models" (p. 193). When relational models are upgraded, two governors are set: Allow Enhanced Portability at Runtime and Generate Dynamic Information. The upgrade process sets the Allow Enhanced Portability at Runtime governor to True. This indicates that the data types were not upgraded yet. For more information, see "Data Types" (p. 26). The upgrade process also sets the Generate Dynamic Information governor to True. When this governor is set and a model contains query subjects but no dimensions, the query engine generates queries that avoid double-counting. This also provides a level of backward compatibility with ReportNet. The verify model process flags a warning when this governor is set to true.

Models Based on SAP Metadata

Query subjects that are based on SAP metadata are not converted to dimensions. Instead, the upgrade process creates a new model query subject having the same name and query items as the original query subject. The model query subject points to the newly created dimensions. Model query subjects that do not contain levels and hierarchies are transformed to measure dimensions.

Data Types
Cognos 8 added support for additional data types. As a result, some existing data types in the model may no longer be correct. Data types are saved in the model to serve as a metadata caching strategy. When data types are stored in the model, the query engine can avoid going to the database to determine the data types for query items, resulting in improved performance. During the model upgrade, the Allow Enhanced Model Portability at Runtime governor is set to True and the status property of all DB query subjects is set to Needs Re-evaluation. When this governor is set, the query engine ignores the data types in the model that are flagged as Needs Re-evaluation and retrieves the data type information for the database. This might have a slightly worsen performance when running reports. When the model is verified after the upgrade, the process flags a warning that the Allow Enhanced Model Portability at Runtime governor is set. For information about handling issues reported while verifying a model, see "Repairing Upgraded Models" (p. 193). Note: When an entire ReportNet system is upgraded, the Allow Enhanced Model Portability at Runtime governor is set. If you turn this governor off, you must republish any packages.

Dimensional Information
If a query subject in a ReportNet 1.x model has dimensional information defined, this information is used to create either determinants or dimensions in Cognos 8. Only the first hierarchy is used. Alternate hierarchies are ignored. For more information, see "Defining Dimensions and Determinants" (p. 222). If a query subject is transformed to a dimension and a related dimension exists, a scope relationship is created. Scope relationships are only created between regular and measure dimensions. During upgrade, sufficient metadata does not exist to create measure dimensions. Query subjects representing measure dimensions must be identified by the modeler and created manually. Scope relationships will be created automatically at this time based on the underlying joins. For more information, see "Define Scope Relationships" (p. 85). If you decide to make changes to the model without verifying it after the upgrade, do not make changes to the determinants because you may lose the dimensional information.

Checklist
You can upgrade ReportNet models to Cognos 8 models by opening the project in Framework Manager. You can then model and publish packages to the portal.

26

Framework Manager

Chapter 2: Designing a Project If you want to upgrade your model and take advantage of the multidimensional features of Cognos 8, follow these steps: Verify the model in your existing ReportNet environment.

Open Framework Manager and upgrade the model. Verify the upgraded model. Perform additional required modeling to make existing models accessible from Analysis
Studio. After the model is upgraded, you can create packages and publish them to Cognos Connection, making them available to report authors. For more information, see "Making Metadata Available to Report Authors" (p. 191).

Verify the Model in Your Existing ReportNet Environment

The upgrade process does not resolve any problems that existed in your model prior to upgrading. Before upgrading the model in Cognos 8, we recommend verifying your model and fixing any reported problems in the ReportNet environment. For more information, see "Verify a Model" (p. 191).

Upgrade the Model in Framework Manager

Upgrading a model prepares the model to take advantage of some of the new features in Cognos 8, such as dimensional modeling and access to OLAP data sources. When you open a ReportNet model in Framework Manager, you are notified that the model was created with an older version of Framework Manager and must be updated. Before upgrading your model, we recommend that you verify the model in your existing ReportNet environment and fix any problems in the ReportNet environment. The upgrade process does not resolve any problems that existed in your model prior to upgrading.

Steps
1. In the Welcome page, click Open a project. Tip: If you have the Framework Manager Project Viewer open, from the File menu, click Open. 2. Browse to locate the project folder, click the .cpf file, and click Open. A message appears indicating that the model must be updated. 3. If you want to specify the location for the backup files, click on the Browse button and select a location. 4. If prompted, provide authentication information to the ReportNet server. 5. Click OK to begin the upgrade. An upgrade summary appears. We recommend that you verify the contents of the upgraded model immediately after upgrading. If you choose not to verify the model, you can publish it as is, but you will not have access to OLAP functionality or dimensional modeling.

Verifying the Upgraded Model

When you verify a model, Framework Manager checks for various problems, such as invalid objects. You can direct Framework Manager to repair the problems. After the model is upgraded and the upgrade summary appears, you can choose to verify the model immediately. If you choose not to verify the model immediately, you can verify it later. Tip: From the Project menu, click Verify Model. Verifying the model separate from the upgrade process offers these advantages: You can open a ReportNet model and upgrade and publish without any changes in query functionality. You can move to dimensions and determinants gradually.

User Guide 27

Chapter 2: Designing a Project You can take the time to reassess model requirements. You can continue to model the production model and publish it without dimensional information. You can apply a methodical approach to fixing the model, such as fixing the model by layers. You can see the individual upgrade steps and make decisions individually.

If you make changes to the model before verifying it, you should not change the determinants. Doing so may result in losing the dimensional information, which will prevent a successful model verification later. For information about resolving problems specific to upgraded models, see "Repairing Upgraded Models" (p. 193).

Model for Analysis Studio

You must enable outer joins between regular dimensions and measure dimensions where there is sparse data in the model (p. 76). Before using your model in Analysis Studio, you have to make some changes to your model. During the upgrade, fact tables cannot be identified and are still query subjects. You must resolve this manually by converting the query subject to a measure dimension.

Steps
1. In the Project Viewer, click the query subject. 2. From the Actions menu, click Convert to Measure Dimension. Query items whose Usage property was set to Fact are now measures.

Use Separate Namespaces

Namespaces are containers like folders. Objects in a Framework Manager project must be uniquely identifiable. If you have two objects that have the same name, they must reside in two separate namespaces. For example, you have a database that contains financial data. One set of tables represents Forecast and Actual information. Both the Forecast and Actual information have tables named Accounts Payable and Accounts Receivable. To import these tables into Framework Manager and use the same table names in the project, you must create two namespaces. You can name one namespace Forecast, and the other namespace Actual. Note: For SAP BW metadata, shortcuts to namespaces are not supported.

Steps
1. Click the model or root namespace and from the Actions menu, click Create, Namespace. 2. Right-click the namespace, click Rename, and give the namespace a descriptive name.

Importing Metadata
You can import metadata into a new project (p. 24) or an existing project. Importing metadata is an operation that can be performed many times to extend the project. You can also export your model to a Common Warehouse Metamodel (CWM) (p. 39). Framework Manager can use the metadata and data from external data sources to build a project. To import metadata, you must indicate which sources you want and where they are located. You can import from only one data source at a time. If you want to import from more than one data source, you must perform multiple imports. If you want to add a project to a repository, you must set up the repository connection (p. 48). You can import metadata from relational databases, such as Oracle, DB2, and Microsoft SQL Server SAP BW data sources 28 Framework Manager

Chapter 2: Designing a Project existing Cognos 8 models Architect models and Impromptu catalogs DecisionStream or Cognos 8 Data Manager models third-party metadata sources XML as a data source

For information about the data source types supported by Cognos, see the Cognos support Web site (http://support.cognos.com). For information about working with data source connections, see "Data Sources" (p. 59)

Duplicate Object Names

When you import metadata, you can select how you want the import to handle duplicate object names. You have the option of not importing the object, or importing and creating a unique name. The advantage of importing everything except these duplicate tables is that you can add new database objects to the project without specifying them individually, and without going through synchronization (p. 55). To import metadata that has the same table names, you must ensure that the target namespaces are different (p. 28). When you import SAP BW metadata, Framework Manager assigns a unique name to each object. Therefore, if you rename an object in the model and then reimport it, Framework Manager recognizes that it already exists. To reimport an object with a different unique name, you can create a new namespace and reimport the object into this namespace.

Import from a Relational Database

When you import metadata from a relational database, you can import all the metadata or select particular object types such as tables, columns, views, synonyms, stored procedures, and functions. You can also import system objects from a relational source. System stored procedures are not supported. Framework Manager supports only user-defined stored procedures. These database objects are mapped to the following Framework Manager objects. Database object table column view synonym procedure function Framework Manager object query subject query item query subject query subject query subject project function

Steps
1. Click the namespace, folder, or segment that you want to import into and, from the Actions menu, click Run Metadata Wizard. 2. Follow the instructions in the Metadata Wizard: Select a data source connection and click Next. If the data source connection you want is not listed, you must first create it (p. 64). Select the check boxes for the objects you want to import. 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. 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.

User Guide 29

Chapter 2: Designing a Project Specify the criteria to use to create relationships and click Import. For more information, see "Verifying Relationships" (p. 73). Import statistics showing a list of objects that could not be imported and a count of objects that were imported are shown. 3. Click Finish. After importing, check the Usage and Regular Aggregate property values (p. 117). Fact tables can contain numeric columns that should not be aggregated, such as exchange rates.

Import from an SAP BW Data Source

When you import from an SAP BW data source, you can import all the metadata or import only the objects you select. For information about mapping SAP BW metadata objects to Framework Manager objects, see "Mapping SAP BW Objects to Framework Manager" (p. 143). Tip: If you want to expose calculated key figures from your BEx queries, you must import the SAP BW Query (p. 31).

Access to SAP BW Metadata and Data

When using an SAP BW data source, users' access to an InfoCube or InfoQuery metadata does not imply that they also have access to data within those objects. To enable Framework Manager to retrieve metadata from SAP BW, access privileges must be set up within the SAP system. To ensure that users have proper access permissions, verify the permissions assigned to the users' roles. The following authorization objects must be configured so that Framework Manager can import information cubes or data sources, known as InfoCubes in the SAP system. Authorization object S_RFC Field Activity Name of RFC to be protected Value 16 - Execute SYST, RSOB, SUGU, RFC1, RS_UNIFICATION, RSAB, SDTX

Type of RFC object to be protected FUGR - Function group S_RS_ICUBE Activity InfoCube sub-object InfoArea InfoCube S_RS_HIER Activity Hierarchy Name InfoObject Version S_TABU_DIS Activity Authorization Group 3 - Display DATA InfoArea_of_the_ InfoCube Name_of_ InfoCube 71 - Analyze Name_of_Hierarchy Name_of_InfoObject Hierarchy_Version 03 - Display &NC&

Tip: &NC& represents any table that does not have an authorization group. For security reasons, create a new authorization group and assign the table RSHIEDIR to it. The new authorization group restricts the users access to the above table only, which is needed by Framework Manager. Create the new authorization group as a customization in the SAP system.

30

Framework Manager

Chapter 2: Designing a Project Tip: You can use the asterisk (*) to represent all values, when it appears alone, or partial values, when used anywhere in a string.

Conformed Dimensions
When you import multiple SAP BW Queries or InfoCubes, there can be two or more hierarchies that contain the same information. You can conform these hierarchies in Framework Manager to create one dimension and one or more shortcuts. A conformed dimension is represented by a dimension with a shortcut to a dimension in a different namespace. The dimension contains a list of data sources in which the dimension exists. If you want to retrieve data from a specific data source, ensure that you import the dimension from this data source before all others. After import, you can also use Framework Manager to conform dimensions within a project. For more information, see "Conform SAP BW Dimensions" (p. 151).

Steps to Access a Secured InfoCube

1. Create a query in Business Explorer (BEx) that accesses the InfoCube. 2. Create an authorization variable for each InfoObject in the underlying InfoCube for which there are authorizations. 3. For each variable, ensure that the Ready for Input option is disabled. By default, this option is enabled. 4. Enable the query for access through OLE DB for OLAP. 5. Save the query. 6. In Framework Manager, reference the query instead of the InfoCube.

Steps to Import from an SAP BW Data Source

1. Ensure that there is a connection to the data source (p. 64). 2. Click the namespace, folder, or segment you want to import into and from the Actions menu, click Run Metadata Wizard. 3. Follow the instructions in the wizard: If the data source connection you want is not listed, you must first create it (p. 64). Select the check boxes for the objects you want to import. After they are imported, query items cannot be deleted without deleting the entire query subject. Select the languages for your project. You can add languages to your project later, but you cannot go back and import the language-specific metadata from the data source. After the import is complete, the language-specific metadata must be added manually. Indicate whether you want Framework Manager to show the short name or the technical name for the dimensions. Indicate whether you want to organize the objects in the model to approximate the organization in BEx. Indicate whether you want to generate conformed dimensions. 4. Click Next. A list of objects that could not be imported appears along with counts of objects that were imported. 5. Click Finish. After importing, you should check the usage and aggregation property values (p. 113). Fact tables can contain numeric columns that should not be aggregated, such as exchange rates. When you want to recreate a query on another SAP BW system, use the SAP BW migration mechanism to transport the query. This ensures that the technical name of each measure remains the same so that any project that references the query can be directed to either system without any modifications to the project.

User Guide 31

Chapter 2: Designing a Project

Import from a Cognos 8 Model

You can import metadata from an existing Cognos 8 model. Note: If you import from another Framework Manager project, expression syntax is not adjusted for each language. For example, you create a Framework Manager project using French as the design language and you use French-specific syntax in calculations and filters. You then create a new project using English as the design language and you import the French project into the new project. Expressions defined in the calculations and filters are invalid. You must manually modify the expression after importing the metadata.

Steps
1. Click the namespace, folder, or segment you want to import into and from the Actions menu, click Run Metadata Wizard. 2. Click Cognos 8 Model and click Next. 3. Locate the Cognos 8 model (.cpf file) that you want, click Open, and click Next. 4. Follow the instructions in the Import wizard: Select the check boxes for the objects that you want to import. 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. 5. Click Next and click Finish.

Import from an Architect Model or an Impromptu Catalog

To import metadata from an Architect model or an Impromptu catalog, you must first convert them to XML files. Because of differences between Cognos Series 7 and Cognos8, after you import the migrated metadata in Framework Manager, additional work is required to test and refine the metadata. For information about the migration of specific Series 7 objects, see the Architect Metadata Migration User Guide and the Impromptu Catalog and Report Migration User Guide on the Cognos support site (http://support.cognos.com).

Steps
1. Ensure that you exported the Architect model or Impromptu catalog. 2. Click the namespace, folder, or segment that you want to import into and, from the Actions menu, click Run Metadata Wizard. 3. Click either Cognos Architect (.xml) or Cognos Impromptu (.xml) and click Next. 4. Locate the Architect or Impromptu XML file that contains the metadata to import. A message in the XML Preview window confirms that you chose a valid XML file. 5. Click Open. 6. Select the namespace containing your Series 7 security information. 7. Click Import. A list of created objects appears. 8. Click the Verify after import check box if you want to verify the imported metadata. 9. Click Finish.

Import from DecisionStream or Cognos 8 Data Manager

You can use Framework Manager to import metadata from an XML file created by DecisionStream or Cognos 8 Data Manager. You can import a physical layer residing in the Physical Metadata namespace

32

Framework Manager

Chapter 2: Designing a Project This layer contains data source query subjects representing the imported tables. The physical layer contains query subjects and physical relationships between query subjects. These physical relationships are inferred from the relationships defined in the import file. Imported tables become Framework Manager query subjects, and surrogate keys become Framework Manager determinants. a dimensional layer residing in the Dimensions namespace This layer contains regular dimensions, measure dimensions, and scope relationships. The regular dimensions may be conformed or non-conformed. The measure dimension objects correspond to the imported stars. The scope relationships are inferred from the relationships defined in the import file. a logical layer residing in the Business View namespace This layer contains shortcuts to the regular and measure dimensions in the Dimension namespace. The shortcuts are organized as star schema groupings, which are namespaces with the same name as the stars from the import file.

The following diagram shows how objects from DecisionStream and Cognos 8 Data Manager are mapped Framework Manager objects.
DecisionStream or Cognos 8 Data Manager objects Framework Manager objects and the corresponding namespace

Query subject Dimension Relationship

Physical Metadata namespace

Regular dimension Star (Fact) Measure dimension Relationship Scope relationship Dimensions namespace

Star Schema Groupings

Star namespace: shortcut to regular dimension Star namespace: shortcut to measure dimension

Business View namespace

Facts
A star maps to a Framework Manager query subject in the Physical Metadata namespace or as a measure dimension in the Dimensions namespace. The following fact attributes are included in the model. Attribute name Table name Short name Business name Description Column name Column type Column length Framework Manager mapping Name of the database query subject that the model query representing the fact is based on Query subject description Custom property Query subject description Query item name Query item data type Query item size

User Guide 33

Chapter 2: Designing a Project

Attribute name Column short name Column business name Column description Column type Table keys

Framework Manager mapping Custom property Custom property Query item description Query item usage Determinants in the Physical Metadata namespace

Connections
A connection maps to a Framework Manager data source. The following data source attributes are included in the model. Attribute name Connection short name Connection business name Connection description Connectivity Connection string Framework Manager mapping Custom property Data source name Data source description type.interface property Custom property

Dimension Builds
A dimension build maps to Framework Manager as a top-level namespace.

Hierarchies
A dimension containing hierarchies, levels and columns map to a Framework Manager regular dimension containing hierarchies, levels, and query items.

Conformed Stars
Conformed stars map to a Framework Manager namespace that resides in the Business View namespace. It contains shortcuts referencing the dimensions. The following conformed star attributes are included in the model. Attribute name Star short name Star business name Star description Facts Dimensions Hierarchies Framework Manager mapping The name of the namespace representing the star The name of the measure dimension representing the fact The description of the measure dimension representing the fact Shortcuts to a measure dimension Shortcuts to a regular dimensions Hierarchies in the regular dimension representing the DecisionStream dimensions

34

Framework Manager

Chapter 2: Designing a Project

Model Properties
The export file contains the following model properties. Attribute name Schema version Catalog version Model short name Model business name Model description Framework Manager mapping Not mapped Custom property The name of the namespace representing the top-level model object Custom property The description of the namespace representing the top-level model object

Steps
1. Click the namespace, folder, or segment that you want to import into and, from the Actions menu, click Run Metadata Wizard. 2. Click Cognos DecisionStream (*.xml) or Cognos 8 Data Manager (*.xml) and click Next. 3. Locate the XML file that contains the metadata to import. A message in the XML Preview window confirms that you chose a valid XML file. 4. Click Open and then click Import. A list of created objects appears. 5. Click the Verify after import check box if you want to verify the imported metadata. 6. Click Finish.

Import From a Third-party Metadata Source

You can use Framework Manager to import metadata from a third-party source. Metadata is imported using a metadata bridge. You can import both third-party metadata and relational metadata into the same model. We recommend that you start with a new Framework Manager model and import the third-party metadata before the relational metadata. This avoids conflicts if you import same-named objects. During a third-party import, data sources are created based on information provided through the import wizard. If at least one physical object in the third-party source references a database schema or catalog or both, one Framework Manager data source is created with its catalog or schema properties set to the names of the catalog or schema defined in the metadata. A generic data source is created for those physical objects that do not reference a catalog or schema. If you want to access metadata from a third-party data source, you must do a physical model import. Not all third-party data sources contain metadata that is appropriate for BI reporting and not all third-party concepts map to Framework Manager. The metadata import is tailored to Framework Manager and only compatible metadata will be imported. All metadata bridges deliver a physical layer that provides the basis for further modeling. The richness of the resulting Framework Manager model is directly related to the richness of the metadata source. Import options are one of these types: Third-party These options are used to extract the metadata from the third-party source. Framework Manager These options are used to create the imported objects in Framework Manager.

User Guide 35

Chapter 2: Designing a Project Tip: Import options are shown in the import wizard. For optimal mapping, always use the default values. For information about troubleshooting third-party metadata sources, see "Troubleshooting" (p. 253)

Multiple Databases
Third-party metadata sources can be based on multiple databases. The best way to import these multiple data sources into Framework Manager is to perform multiple imports. For each import, you select the items that correspond to that specific data source. For example, the first time that you import from a third-party metadata source, you select datasource1 and all the items that correspond to that data source. The next time, you select datasource2 and the items that correspond to that data source. You continue to import until you have imported all the data sources and their corresponding items.

Third-party Options
Metadata is extracted from the third-party data source by the Meta Integration(R) Model Bridge (MIMB). Not all options apply to Framework Manager. For information about supported tools and object mappings, see the Meta Integration Web site.

Framework Manager Options

The Framework Manager options available are the same regardless of the type of metadata source that you select. This table shows the options used to create objects in Framework Manager. Framework Manager options Logical / Physical Representation

Description Specifies how logical and physical objects are represented. Integrated represents the logical and physical objects as one integrated object. This is the default. Separated represents the logical and physical objects as two related objects. Separated (verbose) represents the logical and physical objects as two distinct objects.

Diagram Representation

Specifies whether each diagram is represented as a namespace, a package, or both. Both is the default. None indicates that diagrams are not represented in the project.

Namespace Hierarchy

Specifies whether the hierarchy of packages is kept in the logical namespace, in the physical namespace, or both. Both is the default. None indicates that the hierarchy of packages is not retained.

Export Logical Only Classes Export Logical Only Attributes

Indicates whether logical only classes are extracted along with all their attributes. The default value is Yes. Specifies whether logical only attributes are extracted. Drop indicates that logical information of a class is not extracted if it contains a logical only attribute. Export indicates that logical only attributes are extracted. This is the default. No indicates that logical only attributes are not extracted.

36

Framework Manager

Chapter 2: Designing a Project

Framework Manager options Encoding

Description Specifies the character set of the model. ISO-8859-1 is the Latin 1 encoding. This is the default on all platforms except Windows. Ks_c_5601-1987 is the default Korean encoding. Shift_jis is the default Japanese encoding. utf_8 is the UTF8 encoding. Windows-1252 is the default Windows encoding. This is the default on Windows platforms.

Consistency Check

Specifies the consistency check level. Basic is the recommended consistency check level. Extensive performs a more thorough validation of the model. None indicates that no validation is performed.

Steps to import from a third-party metadata source

Before you can import metadata, there must be a connection to the data source (p. 64). 1. Click the namespace, folder, or segment that you want to import into, and from the Actions menu, click Run Metadata Wizard. 2. Select Third-Party Metadata Sources and click Next. 3. Click the metadata type to import. 4. In the File Name box, browse to locate the file that contains the metadata to import. A message in the XML Preview window confirms that you chose a valid XML file. 5. Click Open and then click Next. 6. In the Third-Party Specific Import Options dialog box, click the options that you want. The options that you see are based on the selected third-party data source. Note: We recommend that you use the default options. These default options optimize the third-party metadata import. If you change the options, you may see unexpected results. To revert back to the default options, click the Use Defaults button. 7. Click Next. 8. In the Framework Manager Specific Import Options dialog box, click the options that you want, and click Next. 9. Follow the instructions in the Metadata Wizard: Select a data source connection and click Next. If the data source connection you want is not listed, you must first create it (p. 64). Select the check boxes for the objects you want to import. 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. Specify the criteria to use to create relationships and click Import. For more information, see "Verifying Relationships" (p. 73). Import statistics showing a list of objects that could not be imported and a count of objects that were imported are shown. 10. Click Finish.

Modeling After a Third-Party Import

The source metadata has a logical structure that is compatible with Cognos 8. During the import this structure is preserved for higher fidelity with the source model.

User Guide 37

Chapter 2: Designing a Project After the import, only the physical metadata is available. Review the model and apply the recommendations for dimensionally modeling a relational data source. You should set the determinants (p. 212)

set the Usage property (p. 111)

Some bridges require fact to be set because this is not available from the metadata source. verify the relationships and cardinality (p. 214)

resolve ambiguous relationships, such as multiple valid relationships, reflexive relationships,

and recursive relationships (p. 218)

Import Using XML as a Data Source

You can import XML as a tabular data source in Framework Manager. An XML data file can be imported locally or from a remote site through a valid URL. You can import the XML data file into Framework Manager and use it to model metadata and create a package. The XML file is validated and parsed at run time, when the query is processed by either Report Studio or Query Studio. If you add the VALIDATE=ON option to the connection string, Framework Manager partially validates the XML file in the <columnList> tag that describes the metadata. For information about supported data types, see "XML Data Types" (p. 373). You must use the xmldata.xsd schema to validate the XML file. The schema is located in the \c8\bin folder. You do not need to specify the location of the schema in the XML file itself. To use XML as a data source, ensure that you do not use Native SQL to access data in an XML file you do not access Binary Large Objects (BLOB) you use only sqlColumns() and sqlTables() metadata calls Other calls return an unsupported function error. the XML file is well-formed and valid Before you import XML as a data source, there must be a connection to the data source (p. 64). If the XML data source is on another computer, you must use an account that has proper permissions to access the data source. To use XML as a data source, you should understand XML, schemas, and other XML-related technology.

Steps
Before you can import metadata, there must be a connection to the data source (p. 64). 1. Click the namespace, folder, or segment that you want to import into, and from the Actions menu, click Run Metadata Wizard. 2. Click the XML data source that you want to import, and click Next.

Use a Project with Multiple Data Sets

You may have to use the same model and reports with different sets of actual data. The data sets may be different databases, accounts, or schemas in a single database. You may encounter multiple data sets when you use a different data set than used in production in large enterprises, where each division has it own data set in OEM applications, which have no direct control over customer data The tables and columns used by the project must be logically the same across all data sets. You must also ensure that the correct data set is identified in each case. Data sources in Framework Manager contain information that identifies the location of any data source tables needed for the query subjects. This information is the name of the data source in the content store, as well as the optional catalog and schema names. Ensure that the catalog and schema names use the desired data set. 38 Framework Manager

Chapter 2: Designing a Project If different content stores are in use, and a different version of the project is deployed to each content store, you can specify the data source information in the project for each site. If you have only one content store, you can publish each project as a separate package. These solutions require a lot of manual maintenance. To reduce this level of maintenance, you can use one of the following options.

Determining the Data Source Information

The simplest solution is to determine the name of the data source in the content store, the name of the catalog, if applicable, and the name of the schema in the database. You can then use these names in all the data sets. If some data sets use the same content store, create a separate connection for each data set in a single content store. For more information, see the Administration and Security Guide. For information about how Framework Manager handles multiple connections, see "Multiple Data Source Connections" (p. 59). Because the data source name in the content store can differ from the name of the customer database, this solution offers a lot of flexibility. However, it still requires that the catalog and schema names be identical across all data sets. Even if all the data sets use the same database type, this may be difficult to ensure. If different database types are involved, it may be impossible. For example, SQL Server has a catalog level, but Oracle does not.

Using User-based Default Data Set Identification

Each database user has access to a default schema and catalog, if applicable. If the schema and catalog are not defined, or if they are blank in the Framework Manager project data source, the default is used. As in the previous solution, this option may be combined with multiple connections so that different users can use different databases for the same data source. However, when you edit a query subject, Framework Manager uses the catalog and schema names in the data sources to match them to items that are dragged to the SQL windows from the data source tree. For this reason, the catalog and schema names cannot be blank in the project data source while you are modeling. Therefore, you must use a macro expression in the catalog and schema of each data source in the project. This ensures that the catalog or schema names are blank at run time, but explicitly sets the catalog or schema you want while modeling.

Steps
1. Create a single session parameter whose value identifies whether you are in design mode. When you are in design mode, set the value of this session parameter to a specific value, such as design. Otherwise, leave the value empty. Tip: If you use a project or override value, you must set it each time you open the model for editing. 2. For each catalog and schema in each project data source, create a parameter map that contains an empty default value a key whose name is the design value of the session parameter above, such as design, and whose value is the name of the design mode catalog or schema for that data source. 3. Select the data source, and replace the catalog and schema property values with a macro that uses the corresponding parameter map and session parameter. For example, use
#$DBSchemaName ($DeployOrDesign) #

Export Metadata
You can export your Framework Manager model as a Common Warehouse Metamodel (CWM) file. CWM is used for exchanging metadata between different data warehouse tools and repositories. Each instance of the CWM metamodel is exchanged using XMI (.xml metadata interchange) documents.

User Guide 39

Chapter 2: Designing a Project When you export a Framework Manager model as a Common Warehouse Metamodel (CWM) file, joins, folders, namespaces, prompts, and calculations are not exported. Only query subjects, query items, and functions are exported. When you export to CWM, we recommend that you use the default options, which optimize the metadata export. Only change these options if you have specific information that affects your export. For more information about export options, see the Meta Integration Web site.

Steps
1. Right-click the root namespace of the metadata you want to export, and click Export Model. You are prompted to save the project. 2. Select the export target. 3. In the File Name box, browse to locate the file that contains the appropriate metadata type and click Save, and then click Next. An example is GoSales_cwm.xml. 4. In the Framework Manager Specific Export Options dialog box, click the options you want. Note: We recommend that you use the default options. These default options optimize the third-party metadata import. If you change the options, you may see unexpected results. To revert back to the default options, click the Use Defaults button. 5. Click Next. 6. In the Third-Party Specific Export Options dialog box, click the options you want. In the Option Description pane, you see a description of the options available. The options are based on the selected third-party data source. For more information, see the third-party data source vendor documentation. Note: We recommend that you use the default options. These default options optimize the third-party metadata export. If you change the options, you may see unexpected results. To revert back to the default options, click the Use Defaults button. 7. Click Next. The input validation results from the export process appear. 8. Click Next and click Finish.

Setting Up a Multilingual Reporting Environment

You can create reports that show data in more than one language and use different regional settings. This means that you can create a single report that can be used by report consumers anywhere in the world. The samples databases provided with Cognos 8 store a selection of text fields, such as names and descriptions, in more than 25 languages to demonstrate a multilingual reporting environment. For information about how data is stored in the samples databases and how the samples databases are set up to use multilingual data, see the Administration and Security Guide. Here is the process for creating a multilingual reporting environment: Use multilingual metadata. The data source administrator can store multilingual data in either individual tables, rows, or columns. For more information about configuring your database for multilingual reporting, see the Administration and Security Guide. Create a multilingual model. Modelers use Framework Manager to add multilingual metadata to the model from any data source type except OLAP. They add multilingual metadata by defining which languages the model supports, translating text strings in the model for things such as object names and descriptions, and defining which languages are exported in each package. If the data source contains multilingual data, modelers can define queries that retrieve data in the default language for the report user. For more information, see the Framework Manager User Guide.

40

Framework Manager

Chapter 2: Designing a Project

Create multilingual maps.

Administrators and modelers use a Windows utility named Map Manager to import maps and update labels for maps in Report Studio. For map features such as country and city names, administrators and modelers can define alternative names to provide multilingual versions of text that appears on the map. For more information, see the Map Manager User Guide. Create a multilingual report. The report author uses Report Studio to create a report that can be viewed in different languages. For example, the report author can specify that text, such as the title, appears in German when the report is opened by a German user. Report authors can also add translations for text objects, and create other language-dependent objects. For more information, see the Report Studio User Guide. Specify the language in which a report is viewed. You can use Cognos Connection to do the following: Define multilingual properties, such as a name, screen tip, and description, for each entry in the portal. Specify the default language to be used when a report is run. Tip: You can specify the default language on the run options page, in the report properties, or in your preferences. Specify a language, other than the default, to be used when a report is run. For more information, see the Cognos Connection User Guide. The data then appears in the language and with the regional settings specified in the user's Web browser options the run options the Cognos Connection preferences Any text that users or authors add appears in the language in which they typed it.

Modeling with Multilingual Data Sources

To enable a project to work with multiple languages, you must set up data sources to support multiple languages.

Multilingual Relational Data Sources

For relational data sources, you can support multiple languages by using one or more of the following: Language-specific database tables The data source should contain the same tables for each supported language. For example, if the Product table supports English, French, and German, the data source has tables named Product_en, Product_fr, and Product_de. Language-specific columns A database table should contain the same columns for each supported language. For example, if the Product table supports English, French, and German, the table has columns for ProductName_en, ProductName_fr, and ProductName_de. Language-specific rows A database table should contain an additional column to identify the language of each row of data, such as a column named LANG. These solutions can make the multilingual data sources large and difficult to manage. You can model a single relational query subject to represent all possible data source languages by using parameter maps and session parameters in the query subject definition. For more information, see "Creating Prompts with Query Macros" (p. 129) and "Supporting Multilingual Metadata" (p. 107). Note: Expression syntax is specific to the design language of the model. If you import objects from a model designed in another language, you may have to adjust the expression syntax. User Guide 41

Chapter 2: Designing a Project

Multilingual Multidimensional Data Sources

For SAP BW metadata, you do not need to use parameters to support multilingual reporting. Since SAP BW automatically provides data in the language that matches the logon settings for the current user. If there is no metadata for the current users language, Framework Manager retrieves data in the default language.

Multiuser Modeling
Multiuser modeling means that multiple users can simultaneously access an application. Framework Manager supports multiuser modeling by using segments (p. 43) Projects can be divided into segments so that different users can look at different parts of the same project at the same time. When you create a segment, you create a new project in a new folder, complete with its own associated project files (p. 23). links (p. 44) Links are created between projects so that different users can refer to a project at the same time as another user is working on it. repository control (p. 48) You can use repository control to help manage your projects across multiple modelers. We recommend that you link to relatively static segments and regularly check the integrity of your project (p. 191).

Setting Up Your Multiuser Modeling Environment

When you set up your multiuser modeling environment, the physical layer must be modeled as completely as possible before segmenting and linking. In preparation for segmenting your model, ensure that the following is true: The namespace in the main project and any links in the project to folders have the same identifier (p. 28). For example, you have a main project and a link in the project to a folder. The folder you link to must exist in a namespace that has the same name as the main project. If the identifier in the main project and that of the linked folder are not the same, any relationships, shortcuts, or expressions that reference objects in the link, from the main project, may not work. All objects in a project have unique identifiers. For example, you have a main project that contains a query subject named NewQS, and a segment in the project. You open the segment, add a new query subject (p. 90) named NewQS, and save the segment. When you open the main project, an error occurs because a query subject named NewQS already exists in the main project. You update any references in both the main project and any segments in the project. For example, you have a main project and a segment in the project. In the main project, you have a relationship (p. 73) named qs1_qs2 that exists between query subject1 and query subject2. The query subject named query subject 2 is in the segment. You open the segment, rename query subject2 to query subject3, and save the segment. When you open the main project, an error occurs because the relationship qs1_qs2 is broken. In Framework Manager, any object that relies on a reference, such as shortcuts, model query subjects, and expressions, also would be affected. For more information, see "Verify a Model" (p. 191). The main project and any segments in the project have the same languages. For example, you have a main project and a segment in the project. In the segment, you defined the languages (p. 108) English and French. You open the main project, add the language Chinese, and save the segment. When you open the segment, an error occurs because the language Chinese is not defined in the segment.

42

Framework Manager

Chapter 2: Designing a Project

Segmenting and Linking Recommendations

You can use Framework Manager to create and link segments, projects, and folders. There are some recommendations for using these features to minimize complexity and ensure stability in a multiuser modeling environment. Note: You can use synchronizing and action logging to return to earlier versions of the main project or a segment (p. 52). It is important to understand that a project segment is a complete project and that changes to that project impact all other projects to which it is linked. In order for the model query subjects to work, there must be a physical layer in each segment that contains a subset of the data source query subjects on which they are based. These data source query subjects provide access to the data and metadata and must be included in the appropriate segments. The physical layer should never be modified in a segment because any changes will be reflected in the linked parent model and will impact all other model segments that share data source query subjects. Likewise, any changes to objects in the parent model will be reflected in the linked child models. Changes may not be apparent outside the model in which they are made until the model is closed and reopened. If you intend to segment your project, we recommend that you: Model the physical layer as completely as possible (p. 42).

Organize the physical layer using namespaces (p. 28).

You should create a namespace for query subjects, calculations, and filters that you expect to be necessary for more than one segment. You should create a namespace for each collection of query subjects that is unique to a planned model segment. Segment the model (p. 43) for each namespace you created.

Use a source code control repository (p. 48) when possible to restrict access and track changes
to your projects and segments.

Create a Segment
You can create a segment so that you can organize a project according to business rules and organizational requirements share and reuse project information The main project has access to the entire model, including the segments. This means that you can make changes to the segments when working in the main project. You create segments either at the folder or namespace level. You can create a new project in a new folder, complete with its own associated project files (p. 23). You can also link the segments (p. 44) to other projects that contain the same information to maintain consistency and reuse information. If you plan to link model segments, ensure to follow the best practises for model segmentation and linking (p. 42). If the segment is open when the main project is updated, the potential exists for updates to be lost. The changes that were last saved to the model overwrite previously saved changes. We recommend that access to the main project be limited and that you avoid updating segments from the main project. When you work with a main project and segments in the main project, there are other things to consider. If you create a main project that contains segments, and the main project is connected to a repository, any new segments created are automatically added to the repository. If you have a project or segment checked in to a repository and you make a change, you are notified that you must check out the project or segment before you can make the change. If you make changes in a segment, you are notified in the main project that changes were made in the main project.

User Guide 43

Chapter 2: Designing a Project When a new segment is created, any existing parameter maps from the main project are copied to the new segment. After the segment is created, parameter maps are unique to each segment and cannot be shared between segments. For example, if you are working in the main project, you can use a parameter map in a query subject belonging to a segment. However, if you open the segment, the parameter map is not available. Before you create segments, consider dividing your project into business units. For example, you have a project named GoSales. You can create two folders, one named Products and the other named Orders. You can divide the GoSales project at the Products folder and at the Orders folder. For information about opening a segment, see "Open a Project" (p. 25).

Steps
1. Click the folder or namespace you want to divide, and from the Project menu, click Create Segment. 2. In the Create Segment dialog box, change any settings you want. Goal Rename the segment This does not change the folder name. You may find it easier to keep the same name for both the folder and the segment. Change the location for the segmented project files Note: You cannot be connected to a repository. Add the segment to a source control repository Note: This option is available only to segments that are not already part of a repository. Click the Repository button. In the Repository Settings pane, select the Add to Repository check box. In the Connection list, choose either to use an existing connection, or configure a new repository connection (p. 48). Action In the Project Name box, type a different name.

In the Location box, enter a location.

3. Click OK. The Project Viewer is refreshed and the icons representing the segmented folder or the segmented namespace are shown.

Create a Link
A link is a shortcut to an existing project (p. 24), segment (p. 43), folder or namespace (p. 141). You create links to help organize work across large projects, to maintain consistency, and to reuse information. For example, the project named Inventory contains the folder named Products. You can create a link from the GoSales Products to Inventory Products. If any changes or additions are made to the Inventory Products folder, you will see them in the GoSales Products folder. Links are defined in the project file (.cpf) that owns them. If the main project has a link to a segment, the link is part of the .cpf file for the main project (p. 23). If you plan to link model segments, ensure to follow the best practises for model segmentation and linking (p. 42). If you link to a namespace and a new data source is added to that namespace, you must add a link to that new data source. The projects you link must have the same languages defined and the same design language. You must create the project, folder, or namespace before you can link to it.

44

Framework Manager

Chapter 2: Designing a Project

Steps
1. In the Project Viewer, click the object you want to link. Tip: You can create links only to folders, namespaces, and projects or segments. 2. From the Project menu, click Link Segment. 3. Locate and click the .cpf file of the segment, folder, or namespace. 4. If you want to add the link to a repository, click the Repository button. For more information, see "Creating Repository Connections" (p. 48). 5. Click Open. If the project you selected requires upgrading, you will be prompted. For more information, see "Upgrading Models from Previous Versions of ReportNet" (p. 25). If the project or repository connection uses a mapped drive letter, you will be prompted to keep the mapped drive letter or to change it to a UNC path. 6. Choose the project or segment to link to: To link to another project, click Add Project, locate the .cpf file and click Open. Select the project and click Add. To link to a segment, click the segment and click Add. 7. Click OK. A new folder appears in the Project Viewer.

Managing Projects
You should organize projects in a meaningful way so that you can easily find them. Within Framework Manager, you can copy (p. 45), move (p. 46), rename (p. 46), and delete (p. 46) projects. You can manage your projects in Framework Manager using repository control (p. 48), segmenting (p. 43), and linking (p. 44). These project management features help maintain version control, organize a project according to business rules and organizational needs, set run-time processing options, and give other users access to sections of the project. Copying, moving, or renaming a project that is under repository control removes all repository information from the project. You can also identify the vendor-specific functions (p. 69) that you want to use for each data source you import into your project. If your project is segmented, the segments are treated as standalone projects. If you save or copy a project within an existing project, it is treated as a segment. For information about creating new projects, see "Create a Project" (p. 24).

Copy a Project
When you copy a project, you create a replica of that project in another location. All files in the project folder, including sub-folders, are copied to the new location. When you make changes to the project in one folder, these changes are not reflected in copies of the project in other folders. Copying a segmented model copies all segments as well as the main project. There may be times when you cannot copy a project and must use Save As instead. Save As is available from the File menu. It saves the current contents of the open project, rather than what is saved on disk. Saving the project with a new name creates a new project folder while saving the project with the existing name overwrites the current project. This is useful if you want to save changes made to a read-only project or if you want to save a project with a different name or to a new location without overwriting the original project. You cannot create a copy of a project in the same folder as the original. If you copy a project under an existing project folder, Framework Manager will treat it like a project segment (p. 43). If a project or segment is open when you copy it, the last saved version is copied.

User Guide 45

Chapter 2: Designing a Project

Steps
1. From the File menu, click Manage Projects, Copy. 2. In the From text box, click the browse button and select the .cpf file for the project you want to copy. Note: The project folder name is shown in the text box. 3. In the To text box, type the project name. By default, the project name and the directory where the project is saved are the same. 4. In the Location text box, type the new location or click the browse button and select the new project location. Note: If the target location is a new folder that does not exist, the copy command creates it. 5. Click OK.

Move a Project
You may decide to move a project if your folder becomes so full that it is difficult to locate particular projects. When you move a project, you are actually copying it to a new folder and deleting it from the current folder. All files in the project folder, including sub-folders, are moved to the new location. Moving a segmented model moves all segments as well as the main project. Before you can move a project, the project must be closed in Framework Manager.

Steps
1. From the File menu, click Manage Projects, Move. 2. In the From text box, click the browse button and select the .cpf file for the project you want to move. Note: The project folder name is shown in the text box. 3. In the To text box, type the new location or click the browse button and select the new project location. Note: If the target location is a new folder that does not exist, the copy command creates it. 4. Click OK.

Rename a Project
When you rename a project, you provide a new name for both the .cpf file and the folder it resides in. Secondary project files and log files keep their original name. If a project appears in the recent projects list on the Framework Manager Welcome page and you proceed to rename it, you cannot open the project by clicking on the link. You must open the project using the Open command on the File menu. Before you can rename a project, the project must be closed in Framework Manager.

Steps
1. From the File menu, click Manage Projects, Rename. 2. In the From text box, click the browse button and select the .cpf file for the project you want to rename. Note: The project folder name is shown in the text box. 3. In the To text box, type the new name for the project and click OK. If the original project folder and .cpf file have the same name, both the folder and .cpf file are renamed.

Delete a Project
You may decide to delete a project because it no longer satisfies your requirements. When you delete a project, the project folder and all its contents, including any user files, are deleted from the file system and sent to the recycle bin. 46 Framework Manager

Chapter 2: Designing a Project If your project is segmented and you delete the main project, the segments are deleted as well. Deleting a project segment only deletes the segment and not the model it is based on. We recommend that you delete segments from within the model. If you delete the segment using the delete option on the File menu, it appears as if the segment still exists within the model. For more information about working with segments, see Segmenting and Linking Recommendations. Before you delete a project, ensure that the project and all its segments are closed. Framework Manager does not support a file locking mechanism so it is possible under certain circumstances to delete a project with open segments. If you delete a project with open segments, the segments can no longer be saved.

Steps
1. From the File menu, click Manage Projects, Delete. 2. In the Project Folder text box, click the browse button and select the .cpf file for the project you want to delete. Note: The project folder name is shown in the text box. 3. Click OK. The project folder and all its contents are deleted.

Create Model Documentation

After you model the metadata, you can create a customizable and printable HTML or XML representation of the model for documentation purposes. This is useful for debugging your model or if your company requires this type of documentation to satisfy process requirements. When you create model documentation, you can document the entire model or you can select a subset of the model. To document the entire model, you click on the top-level namespace. The model documentation shows the selected object and all the properties and children of that object. You can view, save, or print the report in HTML or XML format. If you are viewing the report in XML format, you may want to customize the report output by providing your own XML schema. You can specify the path to the schema in the ModelDocXML section of the fm.ini file, located in the install_location/configuration directory.

Steps
1. Click on the object that you want to document. Tip: Click on the top-level namespace to document the entire model. 2. From the Tools menu, click Model Report. The model report appears. You can change the report format, print, or save the report.

Search for Objects in the Model

Steps
1. Click the Search tab at the bottom of the Tools pane. Tip: If the Tools pane is not visible, click Tools on the View menu. 2. In the Search String box, type the text you want to search for. 3. In the Condition box, select the condition to apply to the search string. Tip: If the condition options are not visible, click the More button. 4. You can change the scope of your search by adding criteria to the Search In, Class, and Property boxes. 5. Click the Search button. The model objects matching the criteria you specified are listed in the bottom portion of the Search pane. Now you can click on the objects and view the properties in the Properties pane.

User Guide 47

Chapter 2: Designing a Project Tip: If the Properties pane is not visible, click Properties on the View menu.

Repository Control
Use repository control to help manage your projects in Framework Manager. You control versions of a project to ensure that each version of a file is recoverable. Repository control also ensures that users in a large organization have access to the most recent changes or versions of a project or segment. You can use Framework Manager to create a connection to a Visual SourceSafe (VSS) or Concurrent Versions System (CVS) repository (p. 48) add a new project to a repository (p. 50) add an existing project to a repository (p. 50) create a local project from a repository (p. 50) After your repository has been set up and projects have been added, you can use Framework Manager to check in and check out a project (p. 50) get the latest version of a project (p. 51) view project history (p. 51) Note: The limitations set by the third-party repositories are incorporated into Framework Manager. For more information, see the vendor documentation for the third-party data source.

Creating Repository Connections

You can use one of these repositories to manage file versions in Framework Manager: Visual SourceSafe (VSS) Concurrent Versions System (CVS) In Framework Manager, you can add a project, segment, link, or namespace to one of the supported repositories. You can view a list of repositories currently supported by Cognos products on the Cognos support site (http://support.cognos.com). For information about installing and configuring these repositories, see the documentation provided by the vendors. You must set up the path to the source control system in Cognos Configuration before you create a repository connection in Framework Manager. For more information, see the Cognos Configuration User Guide.

Create a Repository Using Visual SourceSafe

If you use Visual SourceSafe as your repository, connect to it using your Windows user name and password. When you open a project stored in Visual SourceSafe, you can automatically log on using your Windows user name and password.

Steps
1. 2. 3. 4. 5. 6. 7. 8. Start Visual SourceSafe Administrator. From the Tools menu, click Create Database. Specify where you want to create the database. Select the New 6.0 Database Format check box, and click OK to create the database. From the Users menu, click Open SourceSafe Database. Locate the srcsafe.ini file, and click Open. You can choose to change the database name. Click OK. Click the database you just created, and click Open. A list of the users assigned to the database appears. 9. Ensure that a user with the same credentials as your Windows account exists.

48

Framework Manager

Chapter 2: Designing a Project Tip: To add a user, from the User menu, click Add User and enter the credentials of your Windows account. From the Tools menu, click Options, and on the General tab, select the Use network name for automatic user log in check box. Close Visual SourceSafe Administrator. Using a text editor, open the srcsafe.ini file, and type the following command at the end of the file: Update_No_Change=Update This command ensures that the project is updated each time there is a check in. Save the srcsafe.ini file and close the editor. Start Framework Manager and, from the Welcome page, click Repository, Connection Manager. Tip: If you have Framework Manager open, from the Repository menu, click Connection Manager. Click the New button. In the Connection Name box, type a name for the connection. In the Type list box, click SourceSafe://. In the Settings window, click in the Value pane, and browse to the location of the srcsafe.ini file. Note: Do not include the filename of the srcsafe.ini filename in the location. Click Test. If you specified your path using a drive letter, you will be prompted to replace it with a network (UNC) path. This is recommended if the repository is to be shared with other computers. Press Yes to use the UNC path, or press No to keep the drive letter. Click OK.

10. 11. 12.

13. 14.

15. 16. 17. 18.

19.

20.

Create a Repository Using CVS

You can use Concurrent Versions System (CVS) as a Framework Manager repository.

Steps
1. Create a directory for the CVS repository. An example is C:\cvs_repository. 2. Create a subdirectory named CVSROOT. An example is C:\cvs_repository\CVSROOT. 3. Start Framework Manager and, from the Welcome page, click Repository, Connection Manager. Tip: If you have Framework Manager open, from the Repository menu, click Connection Manager. 4. Click the New button. 5. In the Connection Name box, type a name for the connection. 6. In the Type list box, click SCCS://. 7. In the Settings window, click in the Value pane, and browse to the location of the repository. Do not specify the CVSROOT in the path. The repository location must be different from the location where the new project is stored. An example is C:\cvs_repository. 8. Click Test. If you specified your path using a drive letter, you will be prompted to replace it with a network (UNC) path. This is recommended if the repository is to be shared with other computers. 9. Click OK.

User Guide 49

Chapter 2: Designing a Project

Add a New Project to a Repository

You can add a new project to a repository at the time it is created. For information about creating a new project and adding it to a repository, see "Create a Project" (p. 24).

Add an Existing Project to a Repository

You can add an existing project to a repository. You must be connected to a repository before you can add a project. For information about connecting to a new repository, see "Creating Repository Connections" (p. 48).

Steps
1. 2. 3. 4. 5. 6. In the Project Viewer, click the project that you want to add. From the Repository menu, click Add Project to Repository. In the Connection list box, select the repository connection. In the Location in Repository list box, select a location to add the project and click Select. To keep the project checked out from the repository, click the Keep checked out check box. Click OK.

Create a Local Project From a Repository

You can create a new local project from a repository. If the original project is checked in to the repository or if it is checked out by you, the new local project is created and checked out of the repository. If the project is checked out of the repository by someone else, the new local project is created but it is not connected to the repository. Ensure that the project does not exist on your computer before creating the local project. If a project is already connected to a repository, it should be opened as a normal project.

Steps
1. 2. 3. 4. 5. From the File menu, click Open Project. Click the Repository button. Select the repository connection and the project file in the repository. Select a directory to save the new project. Click the checkbox to keep the new local project attached to the repository. If the checkbox is not checked, a copy of the project will be made. If the checkbox is checked, it attempts to create a local copy of the project and connect it to the repository. If the project is checked out by another user, you will be prompted with the option to open the project as a copy. 6. Click OK.

Check In and Check Out a Project

You can also check your project in and out of one of the supported repositories. You must already have done the following: Set up the source control system in Cognos Configuration. For more information, see the Cognos Configuration User Guide. Created a repository connection (p. 48). Either created a new project (p. 24) or opened an existing project (p. 25), and added the project to a repository. When you check in a project, the main project file (.cpf), the supporting .xml files and the action log files are checked in. For more information about project files, see "Project Files" (p. 23).

50

Framework Manager

Chapter 2: Designing a Project For information about installing and configuring third-party repositories, see the documentation provided by the vendors. If you have a project checked in to a repository and you make a change, you are notified that you must check out the project or segment before you can make the change.

Steps to Check In a Project

1. In Framework Manager, in the Project Viewer, click the project or segment you want to check in. 2. From the Repository menu, click Check In. Tip: To keep your project or segment checked out, select the Keep Checked Out check box. 3. In the Description box, add a description. 4. Click OK.

Steps to Check Out a Project

1. In Framework Manager, in the Project Viewer, click the project or segment you want to check out. 2. From the Repository menu, click Check Out. The icon for the project or segment reflects that the object is checked out.

Steps to Undo Check Out

1. Click the project or segment for which you want to undo the check out. 2. From the Repository menu, click Undo Check Out. A message warns about overwriting any edits made to the project. 3. Click OK.

Get the Latest Version

When you use repository control in Framework Manager, you retrieve the most recent version of the project (.cpf), model.xml, customdata.xml, and log files. For more information, see "The Project Page" (p. 15). When an exclamation mark icon appears next to a project or segment, it indicates that the segment was updated. Refresh the project or segment regularly by pressing F5. If the project you are working in is checked out, you must first check in the main projects and all segments.

Steps
1. Click the project or segment you want. 2. From the Repository menu, click Get Latest Version. 3. Click OK.

View History
Every project or segment that is connected to a repository has a detailed record of its history. You can see version information, comments, and details about the history of the project. The revision history of a project or segment is logged in the repository.xml file. This file is located in the project folder. You can also return the project or segment to a previous version. Any changes or edits made to the project since the last check in are lost. If you have links (p. 44) in your project or segment, you can view the history of those linked segments or projects and see what changes were made. You can synchronize those changes only if the project you are in owns the link (p. 42).

Steps
1. Click the object you want to view. 2. From the Repository menu, click View History.

User Guide 51

Chapter 2: Designing a Project 3. If you want to return the object to a previous version, click the row of the version you want, and click Sync. 4. Click Close.

Recording Transactions in Log Files

In Framework Manager, you can capture, view (p. 52), and play back actions (p. 52) performed on the project. An action log is an XML document that contains a set of transactions, containing one or more actions. Each transaction has a sequence number and one or more actions. Each action is made up of a name and input parameters. Some actions also have output parameters. The action log file is in the project or segment logs folder. You can save individual transactions to a separate log file. You can use the Framework Manager to play back individual transactions (p. 52) or you can use Script Player (p. 53) to play back a combination of transactions. For example, you make changes to a project in a test environment. When it is time to move the project to production, you can play back every action, or series of actions, that you performed in the test environment to create an identical project in the production environment. Note: If the script has dependencies on the existing project, you must ensure that the project is aligned with the script transactions to ensure the desired results.

View Transaction History

You can view the transaction history in a project or segment action log file and then save it as a script.

Steps
1. From the Project menu, click View Transaction History. Tip: To make the dialog box larger, double-click the caption. Double-click again to restore its original size. 2. Click the transaction numbers you want. 3. Click Save as Script, but do not save it in the logs folder. Tip: To view the details of a transaction, click the plus sign (+) next to a transaction number. 4. Click Close.

Play Back Transactions From a Log File

You can choose to play back a specific transaction or a combination of transactions in a project or segment action log file. For example, you make changes to a project in a test environment. When it is time to move the project to production, you can play back every action, or series of actions, that you performed in the project in the test environment. This creates an identical project in the production environment. When you play back transactions from a log file, the script player applies the commands in the log file to the contents of the existing model. If objects created by the log file already exist in the model, errors appear. You must disable or clear any commands that will conflict with the contents of the model. You can then run the script again. Or, you can use the Synchronize command, which begins with an empty model. If you generate your own script outside Framework Manager, time stamps must be in ascending order with no duplicates.

Steps
1. From the Project menu, click Run Script. 2. Select the script you want, and click Open.

52

Framework Manager

Chapter 2: Designing a Project The Script File box shows the name and location of the script file. Tip: To locate another log file, click the folder button. 3. To view the details of a transaction, click the transaction. A list of the transaction details appears in the Status/Transaction Details box. 4. Set the run options that you want. To set the starting point for running the script, select the script and then click the Set the starting point button. You can do this at any time to skip an instruction or run instructions that have already been executed. To set a stop point for the script, select the script and then click the Set the stop point button. You can stop the script to make a manual fix and then continue on from that transaction. Tip: To remove the stopping point, click the Remove the stop point button. To ensure that the project stops on any transaction error, select the Stop on Error check box. 5. Using the toolbar buttons, choose the run action you want. Button Description Runs the script After an error is encountered, clicking this button attempts to re-execute the failed instruction. Skips to the next transaction and runs the script to the end Runs the selected transaction only Skips to the next transaction and stops, but does not run any transactions. The project window is updated as the script is run. 6. Fix any errors encountered by the script either by retargeting objects or modifying the temporary project as required. For information about fixing script errors, see "Fixing Errors Caused by Invalid Objects" (p. 57). 7. When the script has completed, click Accept to accept the changes. Tip: To return the project to its previous state, click Revert.

Running Action Logs in Batch Mode

The Script Player is a command line utility that runs previously created action logs in batch. The Script Player interfaces with the Framework Manager engine and metadata directly, allowing you to bypass the Framework Manager application. You can use action logs that have been created either by the Framework Manager application or manually by using the reference material. It is ideally suited for automated tasks related to model creation and model maintenance. After careful analysis of your log files, you can use the options to run specific transactions. The Script Player reads the command line parameters and either creates a new model or opens an existing one. After that, an action log consisting of a set of transactions is analyzed and each action is executed in sequence. Actions usually change the model. Before the Script Player terminates, the modified model is saved and replaces the original model. Using the options, you can suppress saving the model. This is useful if you are testing action logs. The Script Player maintains an internal log of all executed actions, allowing you to back out of any changes if necessary.

User Guide 53

Chapter 2: Designing a Project The Script Player can be used on UNIX platforms, where the Framework Manager application is not supported.

Syntax
At the command prompt, ensure you navigate to the installation location of the BmtScriptPlayer.exe. Use the following syntax to run the Script Player.
BmtScriptPlayer [-c|-m] <projectname> [-a <actionlogname>][options]

where <projectname> is the name of the project and <actionlogname> is the name of the action log. For example,
BmtScriptPlayer -m goSales.cpf -a import.xml

Options
You can specify how the Script Player runs using the following options. Note: If you are working in a Unix environment, you may want to create a script to hide credentials that are passed on the command line. Option
-a FILEPATH

Description Apply the specified action log. FILEPATH is the path, including the file name, to the action log file. Execute transactions with sequence number equal to or higher than the number specified by NUM. The default is the first transaction. Create a new project. FILEPATH is the path, including the file name, to the models project (.cpf) file. Using this option without specifying an action log results in the creation of an empty model. Note: If the model specified in the FILEPATH already exists, it will be silently replaced.

-b NUM

-c FILEPATH

-e NUM

Execute transactions with sequence number equal to or lower than the number specified by NUM. If the option is not specified, execution ends at the transaction with the highest sequence number or transaction number 9999, whichever comes first. For action logs that contain transactions with sequence numbers 10,000 and higher, this option must be used.

-g

Upgrade the model (if required). If this option is not specified and the model was created with a previous version, execution will terminate. If you specify this option without specifying an action log, only the model upgrade is performed.

-k DIRECTORY -m FILEPATH

Specify the install directory. Open an existing project. FILEPATH is the path, including the file name, to the models project (.cpf) file.

-n

Do not save the model. This option can be used to test action log files.

54

Framework Manager

Chapter 2: Designing a Project

Option
-p PASSWORD -s NAMESPACE -t DIRECTORY -T PASSPORT -u USER -x

Description Authenticate using the specified password (if required). Authenticate using the specified namespace (if required). Specify the template directory. Specify a security passport. A passport is an encrypted string that will allow secure conversations for the plug-ins that need it. Authenticate using the specified user name (if required). Terminate the test run upon a transaction error. By default, the script player will only terminate with severe errors such as an invalid model or action log, and will continue executing, even if some minor transactions fail.

-y PASSPORT

Authenticate using the specified passport (if required). This options overrides other specified credentials (-s, -p, and -u). The Script Player skips authentication and associates the specified passport with the session.

Examples
This table shows some examples of Script Player commands. Command
BmtScriptPlayer -c <projectname> BmtScriptPlayer -c <projectname> -a <actionlogname> BmtScriptPlayer -c <projectname> -a <actionlogname> -b2 -e20 BmtScriptPlayer -m <projectname> -a <actionlogname> -e20 BmtScriptPlayer-m <projectname> -a <actionlogname> -n

Description Create a project. Create a project and apply all the transactions from the action log. Create a project and apply the transactions numbered 2-20 from the action log. Open an existing project and apply the transactions numbered 1-20 from the action log. Open an existing project and apply all the transactions from the action log. Do not save the project.

Synchronize Projects
You can use Framework Manager log files to synchronize your project. You may choose to synchronize your project if you updated metadata in a third-party modeling tool made changes to metadata using a multidimensional modeling tool If your data source is a relational database, you can update only the query subjects (p. 101) and do not need to perform a full project synchronization. You must perform a project synchronization to synchronize changes in a third-party data source.

User Guide 55

Chapter 2: Designing a Project When you synchronize your project, you create a new project by replaying from the log files, all the actions you made in the original project. If you import a subset of a data source, any new objects that were added to the data source are not included when you synchronize. The action log recorded the importing of objects that you originally specified. When you synchronize, only the originally imported objects are re-imported. You can use project synchronization to run the complete action history of the model and update the model's metadata. You can also save portions of the action log to a separate script file for later use, or you can save the entire action log to a script file if you want to build the same model in batch mode. If you encounter errors when trying to run an action log script, see "Fixing Errors Caused by Invalid Objects" (p. 57). After synchronizing, you can choose to accept the new changes and create a new project, or return to the original project. If you accept the new changes, the original project is replaced. Because every action that you made in your project is rerun, synchronization may take a long time. If an object that is referenced by a transaction no longer exists, either because it was renamed or deleted, you will receive errors during the synchronization. For example, if you imported a table named Products and then renamed the table to New Products in your data source, you will receive an error when you synchronize the project. The synchronization cannot detect that the table named New Products was previously imported using a different name. You must manually retarget the object to complete the synchronization. For information about fixing synchronization errors, see "Fixing Errors Caused by Invalid Objects" (p. 57). Before synchronizing a project, you should understand how synchronization impacts segmented (p. 56) and linked (p. 56) models. You should also ensure that data source connections have not changed and that data sources are online. You can check your connections by testing a few key query subjects.

Segmented Models
A segmented model should be synchronized only by synchronizing the main project. The results of synchronizing the entire project are written to the log file of the main project. The ability to synchronize individual segments is lost after the first synchronization of the main project. If you are working in the main project and change a segment, the main log file is updated. If you are working in the segment and make changes, the segment log file is updated. Synchronization commands do not necessarily run in the order they appear in the log files. This happens because it is possible to update segments concurrently and the action logs are replayed based on the time of the original action. Commands may appear to jump between log files, making it difficult to use debugging features such as single stepping.

Linked Models
Log files are contained in the project that is open and not in the model that is updated. If you open a main project and make changes to a linked model, the actions are logged in the log file of the main project. If you then synchronize the linked model, the change is lost because it did not appear in the set of log files that were used in the synchronization. Synchronization can be run only on the main project or a stand-alone segment. You cannot synchronize linked projects or segments in the main project. If the segments are updated by the linked project, the synchronization can produce unpredictable results in the main project. We recommended that you do not use model synchronization in combination with linked projects.

Steps to Synchronize
1. From the Project menu, click Synchronize. 2. We recommend that you create a backup of your Framework Manager project by selecting the Backup project into this directory check box. 3. To view the details of a transaction, click the transaction. A list of the transaction details appears in the Status/Transaction Details box. 4. Set the run options that you want.

56

Framework Manager

Chapter 2: Designing a Project To set the starting point for running the script, select the script and then click the Set the starting point button. You can do this at any time to skip an instruction or run instructions that have already been executed. To set a stop point for the script, select the script and then click the Set the stop point button. You can stop the script to make a manual fix and then continue on from that transaction. Tip: To remove the stopping point, click the Remove the stop point button. To ensure that the project stops on any transaction error, select the Stop on Error check box. 5. Using the toolbar buttons, choose the run action you want. Button Description Runs the script After an error is encountered, clicking this button attempts to re-execute the failed instruction. Skips to the next transaction and runs the script to the end Runs the selected transaction only Skips to the next transaction and stops, but does not run any transactions. The project window is updated as the script is run. 6. Fix any errors encountered by the script either by retargeting objects or modifying the temporary project as required. For information about fixing script errors, see "Fixing Errors Caused by Invalid Objects" (p. 57). 7. When the script has completed, click Accept. The original project is replaced by the contents of the temporary project. Tip: To return the project to its previous state, click Revert.

Fixing Errors Caused by Invalid Objects

You may encounter errors when running script files or verifying models if an object that is referenced by a transaction no longer exists or if you renamed objects. If an object no longer exists, you should retarget the missing object to another object.

Working with Scripts

If you are working with scripts and you retarget an object, all remaining script transactions use the new object. If the script stops for any other reason, you should modify the temporary project to correct the problem. Note: Fixing errors by making changes to the main project can produce unpredictable results. Always fix errors by changing the temporary project.

User Guide 57

Chapter 2: Designing a Project When a script encounters errors, you can choose how you want to resolve the problem. Solution Skip transactions that include this object. Note: We recommend that you attempt to fix errors before skipping transactions. Action Click Exclude and in the Exclude Transactions that Use this Object dialog box, select the level of exclusion you want. The current transaction and all subsequent ones that reference the excluded object are ignored. For example, if a transaction attempts to create a package that uses the excluded object, the package is not created. Click Replace and in the Replace Missing Objects dialog box, select the option you want. Click Stop and then fix the problem in the temporary project

Replace this and all following occurrences of the object. Fix the problem manually.

Retargeting an Object
If a transaction refers to an object that no longer exists, the script stops and a dialog box appears with the name of the problematic object. You can retarget the object by clicking Replace and selecting a new object.

Fixing Other Errors Encountered by the Script

You must fix script errors by modifying the temporary project. Fixing errors by making changes to the main project may produce unpredictable results. Tip: You can move or minimize the Synchronize dialog box to view and modify the project.

58

Framework Manager

Chapter 3: Data Sources

Before you can create models and import metadata, you must have a data source connection. A data source connection supplies the information that Cognos 8 needs to connect to a database. Each data source can contain one or more physical connections to databases. The data source connection specifies the parameters needed to connect to the database, such as the location of the database and the timeout duration. A connection can include credential information and signons. If users have access to more than one connection in a data source, they are prompted to select a data source connection and a signon when they run a report. Their choice is saved for the duration of the session and as a default value for the next time users run the same report.

Working With Data Source Connections

Multiple Data Source Connections
If you have access to more than one data source connection in a data source, you are prompted to select a data source connection when you open a Framework Manager project. You can use multiple data source connections in a single data source to facilitate the migration from one environment to another and maintain the integrity of a project. For example, you can use multiple data source connections to work with metadata from a test data source. You create a new project, using the test data source connection for the GoSales data source. You create and modify the objects you want in the project, and you test that the project is modeled the way you want. When you close the session, and reopen the Framework Manager project, you can select the production data source connection. When you publish the package to the Cognos 8 server, report authors choose which data source connection they want to use in their report. Multiple connections to the same data source must be defined in Cognos Connection. If you wish to support multiple connections for each data source, blank out the data source catalog and schema names, and in Cognos Connection, create a connection for each database. Note: If you are working with multiple cubes containing unlike metadata, we recommend that you use separate data sources for each cube. To be able to expand an OLAP package in the Studios, the internal name of both cubes must be the same. If you want to run saved reports that ran using a different data source connection, the cube name, as well as the dimension, hierarchy, level and attribute names, must be the same in both cubes. If you use a single data source with a separate connection for each cube, the internal names of all the cubes must be the same. For more information about data source connections, see the Administration and Security Guide.

Databases and Sorting Functions

If you use sorting functions such as running-totals in reports, you may need to add a collation sequence to the database connection string to maintain data integrity. Otherwise, when sorting a report that is grouped by one or more columns containing foreign characters, you may get inconsistent results. This is because without the collation sequence information, the default locale is used to sort data, whereas databases may use different collations in their sorting. To prevent sorting inconsistencies, you must add the correct collation sequence to your database connection string when you create a data source or add a connnection. For example, in Oracle, if you specify the collation sequence as Binary at the database level, you should provide the same collation sequence value in the connection string. Here is an example of a connection string for an Oracle database type using the sample gosl database:
ORACLE@GOSL0703@GOSL/GOSL0703@COLSEQ=Binary

User Guide 59

Chapter 3: Data Sources

Isolation Levels
The isolation level specifies how transactions that modify the database are handled. By default, the default object gateway is used. Not all types of database support each isolation level. Some database vendors use different names for the isolation levels. For SAP BW data sources, the isolation level is read-only. The following isolation levels are in increasing order of isolation: Read Uncommitted Changes made by other transactions are immediately available to a transaction. Database type Oracle DB2 MS SQL Server Equivalent isolation level Not applicable Uncommitted read Read uncommitted

Sybase Adaptive Server Enterprise Read uncommitted Informix Dirty read

Read Committed A transaction can access only rows committed by other transactions. Database type Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix Equivalent isolation level Read committed Read stability Read committed Read committed Committed read

Cursor Stability Other transactions cannot update the row in which a transaction is positioned. Database type Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix Equivalent isolation level Not applicable Cursor stability Not applicable Not applicable Cursor stability

Reproducible Read

60

Framework Manager

Chapter 3: Data Sources Rows selected or updated by a transaction cannot be changed by another transaction until the transaction is complete. Database type Oracle Equivalent isolation level Not applicable Execute the statement, "SET TRANSACTION READ ONLY," prior to starting a transaction DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix Repeatable read Repeatable read Repeatable read Repeatable read

Phantom Protection A transaction cannot access rows inserted or deleted since the start of the transaction. Database type Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix Equivalent isolation level Not applicable Not applicable Not applicable Not applicable Not applicable

Serializable A set of transactions executed concurrently produces the same result as if they were performed sequentially. Database Type Oracle DB2 MS SQL Server Sybase Adaptive Server Enterprise Informix Equivalent isolation level Serializable Not applicable Serializable Serializable Not applicable

Types of Data Source Connections

Cognos 8 supports many different types of data sources. The data source connection information may vary for each type of data source you use. The sections below provide information specific to individual data sources. If you require additional information about the parameters to connect to your specific data source, see the vendor documentation for the data source you are using.

User Guide 61

Chapter 3: Data Sources

Cognos Cubes
Cognos 8 provides support for accessing Cognos PowerCubes generated by Transformer 7.2 and later. If you are connecting to secured Cognos Contributor cubes, Cognos Finance cubes, or PowerCubes, you must select the Cognos Series 7 namespace that was referenced when the cube was created. When you use PowerCubes as data sources, we recommend that you optimize them for Cognos 8. Optimized PowerCubes provide faster data retrieval at runtime. For more information about optimizing PowerCubes, see Step-By-Step Transformer. The connection information for PowerCubes provides both a Windows and UNIX path to a cube file. If all of your report servers are installed on Windows computers, you need only use the Windows path. Similarly, if all of your report servers are installed on UNIX computers, then you need only use the UNIX path. If you have report servers installed on both Windows and UNIX computers, you can use both paths to ensure that the report server running the request can access the PowerCube from either Windows or UNIX. In this situation, you would also need to have the cube available to both file systems. This can be accomplished by duplicating the cube in two locations. For example, you can save the PowerCube file to a location available to Windows report servers, and then make a copy and save it to a location that is available to UNIX report servers. In the PowerCube connection string information, you can provide both paths. To ensure that the data returned is the same, the cube file on both the Windows and UNIX environments must be the same. Note: If you are using Framework Manager, the Windows path to the PowerCube is required. If a PowerCube that you have already created a connection for has to be updated, you can update the connection in Cognos 8 without affecting users who may be currently accessing the original PowerCube. If a cube has secured its data using user classes from a Series 7 namespace, you will have to select the namespace to be used for authentication. If the options are disabled or the namespace is not listed, see "Configuring Cognos 8 Components to Use Cognos Series 7" in the Cognos 8 Installation and Configuration Guide for how to identify a Series 7 namespace to your Cognos 8 environment. For information about updating existing data source connections, see the Cognos 8 Administration and Security Guide.

Native Metadata
Cognos 8 supports OLAP data sources as well as relational data sources. We use the term native metadata to refer to objects such as models, packages, and queries that are based on an OLAP data source. A namespace that contains native metadata uses this icon to indicate that it is different from namespaces containing other types of metadata. OLAP data sources are metadata rich data sources. Explicit modeling for these data sources is not enabled in Framework Manager and the package is published directly to the portal. For more information, see "Publish a Package Based on an OLAP Data Source" (p. 208). Levels are created using the generation names in the labels. If you want to alter the way levels are named, you can do this by changing the dimension build settings in the application that generated the cube. For more information, see the vendor documentation. Relational data sources require dimensional modeling to enable them to work in Analysis Studio and to work with drill capabilities in the other web studios. For more information about dimensional modeling, see "Working with Dimensions" (p. 78). If you have installed Cognos 8 components on UNIX servers, we recommend that you also locate the file-based data source on a UNIX server. You should then use a UNIX path, such as /servername/cubes/Great Outdoors Company.mdc to access the file. For more information, see "Recommendation - Use Network Paths for File-Based Data Sources" (p. 66) Compound packages contain both OLAP and relational metadata.

62

Framework Manager

Chapter 3: Data Sources

XML Data Sources

If you create an XML data source, you must use XML as the type of connection and specify the location of the XML document in the connection string. You can specify the connection string for an XML data source as an HTTP URL that identifies the content store required to connect to the XML document. An example is HTTP://xmltestserver.cognos.com/XML/country.xml. Ensure that you create a Web alias for the directory that contains the XML file and that you enable directory browsing. a file path A Windows file path example is \\servername\XML\country.xml. A UNIX file path example is /servername/XML/country.xml. a local file An example is C:\XML\country.xml;VALIDATE=ON. To access a local file, use a file path that uses platform-specific syntax. To test an XML connection string, you must type the following code at the end of the string:
;VALIDATE=ON

The text of this code is not case sensitive.

Parameterized XML Connection Strings

In an HTTP URL connection string for an XML data source, you can use parameters to send additional information. You can embed a prompt definition string in the parameter component. If the prompt definition is specified in the report, that value is used. Otherwise, the user is prompted to supply a value. Prompting is not supported for other types of connection strings. An example of a URL component is addressing_scheme://network_location/path;parameters?query#fragment_idenitifier Encode the parameter component with the definition string in between two sets of question marks. A prompt cannot cross a component boundary. An example of a parameterized XML string is http://My_Network_Location/My_Path/myxml.asp?countrysid=??CanadaPrompt?? Parameterized XML connection strings have these restrictions: When a URL component is a prompt, it cannot contain other data. Prompts embedded in XML connection strings do not work in Framework Manager. You cannot import data from a parameterized XML connection string. When you set up a parameterized XML connection string in Cognos Connection, the Test button does not work. Validation of the query specification in Report Studio does not work if you are connected to a parameterized XML connection string.

Microsoft SQL Server and Microsoft Analysis Services

When connecting to Microsoft SQL Server OLE database, you can select Cognos 8 Service Credentials as the signon for the data source connection. This property instructs Cognos 8 to log on to the SQL Server database using the logon specified for the Cognos 8 service. Users do not require individual database signons. You should not use a Windows local system account for the Cognos 8 server logon with a Microsoft SQL Server OLE data source. When connecting to Microsoft Analysis Services, you must specify a language. You can have only one language selection for a Microsoft Analysis Services data source. For more information, search the Microsoft Web site (http://www.microsoft.com) or Microsoft Support Web site knowledge base (http://support.microsoft.com) for "locale identifier property".

User Guide 63

Chapter 3: Data Sources You must use the following configuration if you use a Microsoft Active Directory namespace and you want to support single signon with Microsoft SQL Server or Microsoft Analysis Server: The Cognos 8 gateway must be installed on an IIS Web server that is configured for Windows Integrated Authentication. Content Manager must be installed on a Windows 2000 or Windows 2003 server. Content Manager, the report server (Application Tier Components), IIS Web server, and the data source server (Microsoft SQL Server or Microsoft Analysis Server) must belong to the Active Directory domain. The data source connection for Microsoft SQL Server or Microsoft Analysis Server must be configured for An External Namespace and that namespace must be the Active Directory namespace. For more information about installation options for the gateway and Content Manager, see the Installation and Configuration Guide. Named sets are imported and stored as read-only calculations in the Framework Manager model. The calculation has a flag that identifies it as a named set, and a property that contains the dimension name.

ODBC Data Sources

If you are connecting to an ODBC data source that has been set up as a user DSN, ensure that the service using the connection is running as the user who created the data source. System DSNs are not restricted to the user who created the data source. When you create connections to ODBC data sources, select the vendor-specific data source type, such as Microsoft SQL Server (ODBC), from the Type menu in the New Connection wizard. On Windows, select ODBC (Windows Only) to connect to an ODBC data source type that does not appear in the menu. On UNIX, you can only connect to a data source with a vendor-specific type. Generic data source types are not supported. Database vendor IBM Red Brick Microsoft SQL Server NCR Teradata ODBC (Windows only) Database code RB SS TD OD

Composite Software
Composite Software lets you retrieve data from different data sources using a single connection. The data sources are managed by Composite Software, and the connections to Composite Software from Cognos 8 are made using an ODBC System DSN. For more information about using Composite, see the Composite Software documentation. For more information about creating the System DSN for Cognos 8, see the ReportNet and Composite Getting Started Guide included with the Composite installation.

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.

64

Framework Manager

Chapter 3: Data Sources 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 only be edited 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
Each data source can contain one or more physical connections to databases. The data source connection specifies the parameters needed to connect to the 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 Directory Administration secured function.

Connections to Specific Data Sources

If you are creating a connection to one of these data sources, review the pertinent information before continuing: Cubes from Cognos products (p. 62) XML data source (p. 63) Microsoft SQL Server (p. 63) Microsoft Analysis Server (p. 63) ODBC data sources (p. 64) Composite data sources (p. 64) Depending on the type of database you are connecting to, you may also need to review information about isolation levels (p. 60) and sorting functions (p. 59).

Steps to Create a Data Source Connection

1. If you are not already using the Run Metadata Import wizard, click the namespace, folder, or segment you want to import into, and from the Actions menu, click Run Metadata Wizard. 2. In the Select Import Source window, click New. 3. 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. 4. In the connection page, click the type of database to which you want to connect, select an isolation level, and then click Next. The connection string page for the selected database appears. 5. 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 connecting:

User Guide 65

Chapter 3: Data Sources 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 Microsoft Analysis Services, select an option in the Language box. 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 Installation and Configuration Guide. If you selected Other Type as the data source type, you will have to 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 Windows User DSN, you must be logged on as the creator of the DSN for the test to succeed. 6. Click Finish. The data source appears as an entry in the Directory tool in the portal, and can be selected when using the Import wizard in Framework Manager. Tip: To test a data source connection, right-click the data source in the Data Sources folder and click Test. If you created a signon, you can now modify the properties of the signon or add more signons.

Recommendation - Use Network Paths for File-Based Data Sources

If you have a distributed installation with several servers, we recommend that you use network paths for all file based data sources rather than local paths. This will ensure that the data sources can be accessed by the services that require them, regardless of which server requires the data. When you create a connection to a file-based data source, such as a PowerCube, you enter a path and filename. You can use a local path, such as C:\cubes\Great Outdoors Company.mdc, or a network path, such as \\servername\cubes\Great Outdoors Company.mdc, to point to the file. In a distributed installation, where report servers are running on different computers, using a local path would require that the file and path be valid on each computer where a report server is running. Alternatively, if you use a network path to point to a file, each report server would point to the same file on the network without having the file available locally. Also, to ensure that the file is always available, we recommend that you store it in a shared directory that can be accessed on your network. If you have installed Cognos 8 components on UNIX servers, we recommend that you also locate the file-based data source on a UNIX server. You should then use a UNIX path, such as /servername/cubes/Great Outdoors Company.mdc to access the file. If you have installed all components on a single computer, you can use local paths, but you must ensure that the services requesting the data have the appropriate access to the data files on the computer. For Windows distributed installations, we recommend that you use UNC paths to shared directories for any file based data source, such as PowerCubes or XML files.

66

Framework Manager

Chapter 3: Data Sources

Modifying Data Source Properties

You can modify the properties of a data source that was created using the Metadata Wizard in Framework Manager. The data source properties help you control and optimize the way queries are run against the database. You cannot modify the properties of a data source that was created using the portal. These data sources can only be modified in the portal. For more information, see the Administration and Security Guide. Data Source Property Name Query Processing Rollup Processing Content Manager Data Source Description Descriptive name of the data source connection provided by the user at the time of creation Determines whether SQL processing is performed by the database server or processed locally Determines whether aggregate rollups are computed locally or in the database Specifies the name of the data source as it is identified in the Content Manager. If using an XML data source, this property may be parameterized. Represents different information for different databases. For example, if the database is SQL Server, the element contains the name of the database; if the database is Oracle, it is not used. Specifies the name of the cube Represents different information for different databases. For example, for SQL Server or Oracle, the element contains the name of the owner. Specifies the type for the parent object. Specifies the type of query model that this data source understands. For example, SQL sources are relational and MDS sources are multidimensional. This element contains two letters, identifying the provider type. It is maintained by the application. Defines the function set that applies to a data source. Used in the initial population of the function sets of a security view when a package is created. References a parameterMap that represents a DB2OLAP alias table map.

Catalog

Cube Schema

Type Query Type

Query Interface Function Set ID

Parameter Maps

Example - Moving a Relational Model from One Environment to Another

You want to move a model from a test environment to a production environment. This example is based on the GO Sales data warehouse, which accesses Microsoft SQL Server. You can change the data source of a model from one relational vendor to another relational vendor. It does not matter if the data is dimensionally modeled. You cannot change the data source of a model from a relational vendor to an OLAP data source. You cannot change the data source of a model from one OLAP data source to another OLAP data source. User Guide 67

Chapter 3: Data Sources

Steps
1. Create two parameter maps, one for the Catalog property and one for the Schema property of the data source. These parameter maps are used in macros to set the properties of the data source at run-time. Here is the Datasource_Catalog parameter map. Key TEST_USER PRODUCTION_USER Value GOSLDW_TEST GOSLDW_PRODUCTION

Here is the Datasource_Schema parameter map. Key _MSSQL_TEST _MSSQL_ODBC_PRODUCTION Value dbo dbo

2. In the Catalog property for the data source, insert a macro that uses a value in the Datasource_Catalog parameter map based on the account.defaultName session parameter. The syntax looks like this:
#$Datasource_Catalog {$account.defaultName}#

3. In the Schema property for the data source, insert a macro that uses a value in the Datasource_Schema parameter map. The syntax looks like this:
#$Datasource_Schema {$account.defaultName}#

Specify Where Aggregate Rollups are Processed

The Rollup Processing property for data sources determines whether aggregate rollups above the lowest level are computed locally or in the database. The default is set to local if local query processing is enabled, and is set to database otherwise. Note: This property is not applicable for SAP BW data sources. The possible options for this property are: unspecified The aggregation rollup is not specified. local All aggregation rollups are computed locally (in the report server) using a running aggregate (for example, RSUM). Running aggregates spread the cost of this computation as the data is retrieved. Use this option if the local computer has more idle resources than the database computer, or if you find through experiment that it is the fastest method. database Aggregation rollups are computed by the underlying database software if possible. Otherwise, they are computed locally (provided local query processing is enabled). Running aggregates are used, but the cost is incurred by the database server instead of the report server. Use this option if the database computer has more idle resources than the local computer, or if you find through experiment that it is the fastest method. extended All aggregation rollups are computed by the database server using an extended aggregate (for example, XSUM). Extended aggregates incur the entire cost of this computation up front. Typically, this is the fastest method, but only where the database is set up to take advantage of materialized views. For databases where OLAP functionality is supported, this is translated into the appropriate OLAP aggregate functions. 68 Framework Manager

Chapter 3: Data Sources

Steps
1. In the Project Viewer, click the data source you want to change. 2. In the Properties pane, in the Rollup Processing list box, select the type of rollup processing you want.

Improve Performance by Setting Query Processing Type

The query processing property for data sources determines whether SQL processing is performed by the database server or if it is processed locally. For relational metadata, you can improve performance by selecting the right type of query processing. There are two types of query processing: limited local The database server does as much of the SQL processing and execution as possible. However, some reports or report sections use local SQL processing. database only The database server does all the SQL processing and execution. An error appears if any reports or report sections require local SQL processing. Although the database server can usually run the SQL and run reports much faster, local processing is sometimes necessary. For example, choose limited local processing if you want to create cross database joins or if you want report authors to use unsupported SQL99 functions. Some complex queries require limited local processing, such as a query that must generate an At clause to avoid double-counting. In this case, the query automatically uses limited local processing even if the package was published with database only processing. For information about optimizing SAP BW performance, see "Optimizing SAP BW Performance" (p. 187).

Steps
1. In the Project Viewer, click the data source you want to change. 2. In the Properties pane, in the Query Processing list box, click either Limited Local or Database Only.

Using Functions to Create Expressions

The Expression Editor provides a list of functions that you can select to create an expression. This list includes: common SQL99 functions vendor-specific functions functions imported from a data source free-form functions When you import metadata into Framework Manager, you import the functions from the metadata source. These functions are shown in a folder whose name matches the namespace. This folder is located at the bottom of the list of folders in Expression Editor.

Select Function Sets

A collection of database functions that are vendor-specific is called a function set. When you create a project that contains relational metadata, the Expression Editor lists the function sets for all available vendors. However, you can restrict the function sets so that they list only the vendors that you want to use in your project. You customize the function set by identifying the specific vendor for each data source defined in the project.

User Guide 69

Chapter 3: Data Sources Functions that you defined in your relational data source can be used in Framework Manager. If you imported the user-defined functions, they are listed in Framework Manager for easy selection. If you did not import them, you can type the name of the function into an expression. If the function must be qualified, you must import them into Framework Manager. If an unrecognized function is typed into a report, it is assumed that the function is native. For more information, see "Native SQL" (p. 105). Note: When you create a project that contains SAP BW metadata, Framework Manager automatically lists only the functions that apply to SAP BW data.

Steps
1. From the Project menu, click Project Function List. 2. Select the Set function list based on the data source type check box. Tip: To disable this filter, select the Include all function sets check box. 3. In the Function set page, click the appropriate data source row. 4. Select the function set you want to use with this data source. 5. Repeat steps 2 to 4 until finished. 6. Click OK. For information about how to specify which function sets are included in individual packages, see "Create or Modify a Package" (p. 197).

Quality of Service
Framework Manager allows you to query any combination of data source types, but not all data sources support functions the same way. The quality of service indicator provides modelers and report authors with a visual clue about the behavior of individual functions when used in conjunction with the data sources in the model. Each function specified in your data source may have a different quality of service, depending on the type of data source in use. For each query feature that does not have the same quality of service across packages, the modeler is able to override the level of service and add text to describe the specific situation in that model. Report authors can see the quality of service indicators and the context specific description, and use this information when determining which functions to use in reports. The quality of service for a function is specified at the data source level and can be set for an individual function or for all functions in a package. The available options are: Not Available - the function is not available for any data sources in the package Limited Availability - the function is not available for some data sources in the package Poor Performance - the function is available for all data sources in the package but may have poor performance in some data sources Unconstrained - the function is available for all data sources If there is more than one type of data source in the model, the quality of service values are aggregated according to the following rules: If the quality of service is defined as Unconstrained, Poor Performance, or Limited Availability in one data source and defined as Not Available in another data source, the quality of service for that function becomes Limited Availability. In all other cases, the lowest common dominator is used. For example, if the quality of service is Unconstrained in one data source and Poor Performance in another data source, the quality of service for that function becomes Poor Performance. If the quality of service is Poor Performance in one data source and Limited Availability in another data source, the quality of service is reported as Limited Availability.

70

Framework Manager

Chapter 3: Data Sources

Impact of Overriding the Quality of Service Indicator

Framework Manager determines the quality of service for functions based upon the data source type. Taking into consideration the context of the model, the modeler has the ability to override the quality of service that is determined by the product. Overriding the quality of service provides guidance to report authors. It does not change the level of support for that function in your data source. When a package is made by combining sub-packages, quality of service overrides in the parent package take precedence. If there is no parent override, the quality of service for the child packages are aggregated as described above.

Consider Your Report Authors

Ultimately, the goal is to provide report authors with enough information to satisfy their business requirements, but not enough to confuse them. If your report authors are unable to make decisions regarding which functions to use based on the quality of service indicators, you should consider publishing separate packages for different groups of users. If your report authors require access to functions whose quality of service is less than Unconstrained, you should document the restrictions of those functions when you set the quality of service.

Impacts on Performance
The quality of service indicators have no direct impact on query performance. They are intended to give the modeler some control over which functions are available for use. This allows the modeler to prevent report authors from using functions that could result in long running queries or queries that fail. It is important to note that if you use functions that are not available in your data source, Framework Manager tries to compensate by using local processing on the report server. This may have an impact on query performance because the work is done on your report server instead of on your data source server. In some situations, local processing may require more data to be retrieved from the data source server, which has an impact on both the data source server and the network. For example, OLAP functions are not available in a relational data source. If you attempt to use OLAP functions with a relational data source, Framework Manager uses the dimensional information in the data source to generate a local cube and run the OLAP functions against the cube. This requires retrieval of dimensional information from the data source server and extra processing on the report server.

Steps
1. 2. 3. 4. From the Project menu, select Project Function List. Click the Define Quality of Service button. Expand the tree nodes to view the quality of service for each function. To override the quality of service, click the arrow beside each function and select the quality of service indicator from the drop down list. 5. After changing the quality of service, you can add detailed information about the function in the text box on the right. This information becomes available to your report authors and can assist them in determining whether to use this function in their reports. Tip: Click Remove override to set the quality of service back to the default. 6. Click OK.

User Guide 71

Chapter 3: Data Sources

72

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

After importing metadata, you must ensure that it is set up to meet your users' reporting requirements, and provide any additional information that they require. Enhancements you make in Framework Manager do not affect the original data source. Tip: To verify that the model meets the reporting requirements, you can select objects that will appear in a report and test them. The test results show you the report that your users will see. Or you can publish a package at any time and then use the package to create reports. You can check the project at any time to ensure that the references between the objects it contains are valid. Note: Information on SAP BW metadata is in "Preparing SAP BW Metadata for Use in Reports" (p. 143).

Import View
To ensure that the metadata is set up correctly in the import view, do the following: Ensure that the relationships reflect the reporting requirements (p. 73).

Optimize and customize the data retrieved by dimensions (p. 78). Optimize and customize the data retrieved by query subjects (p. 89). Handle support for multilingual metadata (p. 107). Control how data is used and formatted by checking query item properties (p. 111).

Business View
To enhance the metadata in the business view, do the following: Add business rules, such as calculations, filters, and prompts, that define the information users can retrieve (p. 120). Organize the model by creating separate views for each user group that reflect the business concepts familiar to your users. (p. 136)

Verifying Relationships
A relationship describes how to create a relational query for multiple objects, such as dimensions and query subjects. Without relationships, these objects are isolated sets of data. Relationships work in both directions. You often must examine both directions to fully understand the relationship. The different types of relationships are one-to-one One-to-one relationships occur when one instance of data in a query subject relates to exactly one instance of another. For example, each student has one student number. one-to-many or zero-to-many One-to-many or zero-to-many relationships occur when one instance of data in a query subject relates to many instances of another. For example, each teacher has many students. many-to-many Many-to-many relationships occur when many instances of data in a query subject relate to many instances of another. For example, many students have many teachers.

User Guide 73

Chapter 4: Preparing Relational Metadata for Use in Reports When importing metadata, Framework Manager can create relationships between objects in the model based on the primary and foreign keys in the data source. You can create or remove relationships in the model so that the model better represents the logical structure of your business. After you import metadata, verify that the relationships you require exist in the project and that the cardinality is set correctly. The data source may have been designed without using referential integrity. Often, many primary and unique key constraints are not specified. Without these constraints, Framework Manager cannot generate the necessary relationships between fact tables and dimension tables. Framework Manager stores relationships in the nearest common parent of the objects that participate in the relationship. The parent can be either a folder or a namespace. If you move one of the participating objects outside the common parent, the relationship moves to the next namespace that is common to both ends of the relationship. If you move a relationship to a different folder or namespace, the participating objects also move to the same folder or namespace.

Tips
You can use the Summary tab (Tools pane) to show all the join objects. Under Statistics, click Relationship. If you select a relationship by clicking its line, Framework Manager highlights the columns that participate in the selected relationship. You can use the Search tab (Tools pane) to find an object of class Relationship whose name matches a specified pattern. For example, if you search for a relationship whose name contains Order Header, Framework Manager finds all relationships that have Order Header as one end. If you renamed a relationship, a search of this type may not find it.

Cardinality
Cardinality indicates the nature of the relationship between two objects. Cardinality affects query behavior by applying rules regarding the granularity of data that an individual object returns and regarding the consequence of joins between objects. The cardinality specified in the relationship between query subjects or dimensions determines how and when Cognos 8 generates stitched queries. A stitched query uses multiple subqueries, one for each star, brought together by a full outer join on the common keys. Stitched queries are needed for multiple-fact querying across conformed dimensions and across different levels of granularity. When cardinality is combined with dimensions to control how queries are generated, you can prevent double-counting automatically resolve loop joins enable cross-fact querying for reporting and analysis You can create model dimensions and data source dimensions. Model dimensions are built on a foundation of query subjects that use determinants and relationships with cardinality. Data source dimensions contain their own SQL and use hierarchy and level information as well as relationships with cardinality to define query granularity. You must ensure that all relationships and cardinality correctly reflect your users reporting requirements. For more information, see "Checking Imported Metadata" (p. 213) and "Resolving Ambiguous Relationships" (p. 218).

Detecting Cardinality from the Data Source

When importing from a relational data source, cardinality is detected based on a set of rules that you specify. The available options are use primary and foreign keys use matching query item names that represent uniquely indexed columns use matching query item names The most common situation is to use primary and foreign keys as well as matching query items that represent uniquely indexed columns. The information is used to set some properties of query items as well as to generate relationships.

74

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports To view the index and key information that was imported, right-click a query subject or regular dimension and click Edit Definition. For a query subject, you can change the information in the Determinants tab. All regular dimensions begin as query subjects. If you converted a query subject to a regular dimension, note that determinant information for the query subject is leveraged as a starting point to define the levels of a single hierarchy. We recommend that you review the levels and keys created in the hierarchy of the dimension. Optional relationships, full outer joins, and many-to-many relationships can be imported from your data source. Framework Manager will execute them as queries. Reflexive relationships can be imported from your data source and appear in the model but Framework Manager does not execute them as queries. Although you can view the metadata that defines the reflexive relationship, you cannot edit a reflexive relationship in Framework Manager.

Notation
By default, Framework Manager uses Merise notation. Merise notation marks each end of the relationship with the minimum and maximum cardinality of that end. You can also use Crowsfeet notation, which provides a pictorial representation of the relationship. When you interpret cardinality, you must consider the notation that appears at both ends of the relationship. Possible end labels are 0..1 (zero or one match) 1..1 (exactly one match) 0..n (zero or more matches) 1..n (one or more matches) The first part of the notation specifies the type of join for this relationship: an inner join (1) An inner join shows all matching rows from both objects. an outer join (0) An outer join shows everything from both objects, including the items that do not match. An outer join can be qualified as full, left, or right. Left and right outer joins take everything from the left or right side of the relationship respectively and only what matches from the other side. Data in one object may have no match in the other object. However, if the relationship has a minimum cardinality of 1, an inner join is always used and these records are ignored. Conversely, if all the items match but the relationship in the model has a minimum cardinality of 0, an outer join is always used, although the results are the same with an inner join. For example, the underlying table for one object contains a mandatory (non-NULLable) foreign key for the other. Ensure that the data and cardinalities match. Your users see a different report depending on whether you use an inner or outer join. For example, your users want a report that lists salespeople and orders. If you use an outer join to connect salespeople and orders, the report shows all salespeople, regardless of whether they have any orders. If you use an inner join, the report shows only the salespeople who have placed orders. The second part of the notation defines the relationship of query items between the objects.

Cardinality in Generated Queries

Framework Manager supports both minimum-maximum cardinality and mandatory-optional cardinality.
0:1 - 0 is the minimum cardinality, 1 is the maximum cardinality 1:n - 1 is the minimum cardinality, n is the maximum cardinality

A relationship with cardinality 1-n can be specified as 1:1 to 1:n when reading the maximum cardinalities. The minimum cardinality of 1 is set to 0 for optional data. Therefore a 1-n relationship can also be specified as 0:1 to 0:n, 0:1 to 1:n, or 1:1 to 0:n. The basic rules for how cardinality is used are the following:

User Guide 75

Chapter 4: Preparing Relational Metadata for Use in Reports Cardinality is applied in the context of a query, meaning that only the cardinalities of items explicitly included in the query are evaluated. 1-n cardinality implies fact on the n side and implies dimension on the 1 side. A query subject can behave as a dimension in one query and as a fact in another. Queries on more than one fact will result in a stitched query.

Sparse Data
When modeling for analysis or reporting, it is important to consider the nature of the business questions vs. the nature of the data source. A common scenario is that a relationship between a dimension and a fact table in a star schema is optional. This means that not every dimensional member is mandatory in the fact table. OLAP engines compensate for this by inserting an appropriate value when creating the OLAP structure for any dimensional intersection points that do not have data. When modeling, it is common to override optional relationships between dimensions and facts for improved performance. However, when performing analysis or reporting on sparse data where you require information about dimensional members that have no facts, outer joins must be enabled to ensure that data is returned. To enable outer joins, we recommend that you do the following: Check with your database administrator that the data source can support full outer joins. Import metadata with outer joins enabled. If you do not enable outer joins, data will not be returned for valid dimensional intersection points. For example, an Analysis Studio user wants to create this report: 2004 Canada Mexico United States 500,000 1,000,000 2005 1,000,000 750,000 2,000,000

Because the intersection of Canada and 2004 does not contain a value, the user will not see data. Using outer joins ensures that all missing values are returned as nulls.

Modify a Relationship
After you import data (p. 28) or create a relationship (p. 77) in Framework Manager, you can rename the relationship and redefine cardinality. You can create custom relationship expressions by selecting an operator from the list or by manually changing the expression in the expression editor. You can view the relationships that already exist for an object by selecting the object and clicking Launch Context Explorer from the Tools menu.

Steps
1. Click a relationship and, from the Actions menu, click Edit Definition. 2. To modify existing elements, on the Relationship Expression tab, select the query items, cardinalities, and operator you want. The query items must have the same data type. 3. To create an additional join, on the Relationship Expression tab, click New Link, and define the new relationship. 4. To create a complex expression, on the Relationship Expression tab, click the ellipses (...) button, define the expression, and click OK.

76

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports If you insert session parameters (p. 128) or prompts (p. 125) and you want to specify the values that they represent when you test the expression, click the options button. 5. To test the relationship, on the Relationship SQL tab, identify the number of rows you want returned and click Test. 6. Click OK. If your metadata is from an OLAP data source, click Close.

Create a Relationship
You create a relationship to join logically related objects that report authors want to combine in a single report. This is useful for relationships between objects that were not selected during metadata import, were not joined in the data source, or are from multiple sources. You can directly create a relationship between the query items. You can also use Framework Manager to automatically generate relationships (p. 78) between objects based on selected criteria. You can view the relationships that already exist for an object by selecting the object and clicking Launch Context Explorer from the Tools menu.

Steps
1. Ctrl+click two or more dimensions, query subjects, or query items. Tip: On the Diagram tab, you can also select a query item in a shortcut to create a relationship. 2. From the Actions menu, click Create, Relationship. If this relationship is a valid target for a relationship shortcut, Framework Manager asks if you want to create a shortcut to that relationship. For more information, see "Create a Relationship Shortcut" (p. 77). 3. Click OK. The Relationship Definition dialog box appears. You can use this dialog box to modify the relationship. (p. 76)

Create a Relationship Shortcut

A relationship shortcut references an existing relationship. You can use relationship shortcuts to reuse the definition of an existing relationship. Any changes to the source relationship are automatically reflected in the shortcut. You can also use relationship shortcuts to resolve ambiguous relationships between query subjects (p. 218). Framework Manager asks whether you want to create a relationship shortcut whenever you create a relationship and both of the following conditions apply: At least one end for the new relationship is a shortcut. A relationship exists between the original objects.

Steps
1. Ctrl+click the objects that you want to participate in the relationship shortcut. 2. From the Actions menu, click Create, Relationship. Framework Manager asks if you want to create a shortcut to that relationship. 3. Click Yes. A list appears of all relationships in which one end is a model object and the other end is either another model object or a shortcut to another model object. 4. To retrieve all relationships in which both ends can be either a model object or a shortcut to a model object, click Find All. 5. Click the relationship that you want to be the target of the relationship shortcut. 6. Click OK.

User Guide 77

Chapter 4: Preparing Relational Metadata for Use in Reports

Detect and Generate Relationships

You can use Framework Manager to detect and generate relationships between two or more existing objects in your model. This is useful when you import metadata in stages, or when you want to change the criteria that apply to existing relationships, such as whether they include outer joins. When importing star schema metadata, avoid generating relationships based on matching column or query item names. Data warehouses often apply naming standards to columns, such as surr_key as the default column name for surrogate keys in dimensions. In this case, generating relationships that are based on matching column names generates inappropriate relationships between all dimension tables.

Steps
1. Ctrl+click two or more objects. 2. From the Tools menu, click Detect Relationships. 3. Select the rules you want to apply to each pair of tables. Rule Use primary and foreign keys Use matching query item names that represent uniquely indexed columns Use matching query item names Result Creates joins that are based on primary key and foreign key relationships. The query item names do not have to match. Creates joins between query items whose names and data types match, if one or both of the underlying columns are uniquely indexed. Creates joins between query items whose names and data types match. This generates as many relationships as possible.

4. Indicate whether you want Framework Manager to detect and generate relationships between the selected objects between each selected object and every object in the project that is not selected between the selected objects and every other object in the project 5. Identify whether you want Framework Manager to create outer joins or inner joins based on outer joins that exist in the data source. 6. Click OK.

Working with Dimensions

For information about dimensions based on SAP BW metadata, see (p. 144). A dimension is a broad grouping of descriptive data about a major aspect of a business, such as products, dates, or markets. The types of dimensions that you can work with in Framework Manager are regular dimensions and measure dimensions. In SAP BW, measure dimensions are called key figures. Each regular dimension consists of one or more hierarchies that typically contain several levels. For example, in a project for sales analysis, you include these dimensions: Name Time Region Type Regular dimension Regular dimension Description Dates of sales organized into years, quarters, months, weeks, and days when sales were made Locations of sales grouped into sales regions, countries, and cities

78

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Name Product Customer Sales

Type Regular dimension Regular dimension Measure dimension

Description Product details organized by product type, brand, model, color, and packaging Customer information Purchase details such as units sold, revenue, and profit

You must use regular and measure dimensions to enable analysis on your relational data source. In most data sources, measure dimensions are likely to be shared by more than one regular dimension. Regular dimensions are often called shared dimensions. A measure dimension and regular dimensions organized into a cluster is often referred to as a star schema group but can also be referred to as a functional or subject area group. If the source of a dimension is SQL statements, the dimension is a data source dimension. If the source is other objects in the model, it is a model dimension. A model can contain data source regular dimensions, model regular dimensions, data source measure dimensions, and model measure dimensions.

Normalized Data Sources

Normalized or snowflaked data sources often have several tables that describe a single business concept. For example, a normalized representation of Product may include four tables related by 1-n relationships. Each Product Line has one or more Product Types. Each Product Type has one or more Products. Products have names and descriptions in multiple languages so they exist in a Product Lookup table.

An end user may not know the relationship between the individual query subjects. In addition, having to expand each query subject or dimension and select a query item requires more clicks for the end user. When modeling dimensionally, you can create a regular dimension for Product that simplifies using Product for the purpose of ad hoc query and reporting, and presents the levels of the hierarchy as a visual cue about the relationship between the levels. If you are maintaining a ReportNet 1.x model, you can create a model query subject with determinants instead of a regular dimension. You can replicate the presentation effect of levels by using query item folders. The resulting model query subject can be converted to a regular dimension at any time. For more information, see "Create a Regular Dimension" (p. 79) and "Create a Measure Dimension" (p. 84). For information about creating regular dimensions, see (p. 79) creating measure dimensions, see (p. 84).

Create a Regular Dimension

For information about creating a regular dimension for SAP BW metadata, see (p. 145).

User Guide 79

Chapter 4: Preparing Relational Metadata for Use in Reports A regular dimension contains descriptive and business key information and organizes the information in a hierarchy, from the highest level of granularity to the lowest. It usually has multiple levels and may have multiple key segments to define a level. It may also have multiple hierarchies. Only a single hierarchy can be defined on a data source regular dimension or any regular dimension that participates directly in a relationship. Use regular dimensions to organize and present descriptive information to guide the end user experience in the report authoring tools. When you are using data source dimensions, we recommend that you create all levels that may be necessary for reporting instead of only those levels that are immediately necessary. When you are using model dimensions, begin with the query subjects that are the basis for the dimension. A model dimension can have more than one hierarchy. If it is a multiple-grain query, we recommend that you create a determinant in the query subject for each level that may participate in a join. When creating regular dimensions, you must understand the dimensionality of the data. You must be able to answer the following questions: What are the levels in your dimension? What is the order and combination of levels that form hierarchies? What are the relationships between the levels? What uniquely identifies a level? Which data elements are associated at each level? Do you have more than one level of granularity, such as some data is recorded monthly and some is recorded daily? Are foreign keys defined in the data source? In addition to creating regular dimensions, you can also merge dimensions into a single dimension or convert query subjects to dimensions.

Steps
1. Select a namespace or folder where you want to place the dimension. From the Actions menu, click Create, Regular Dimension, and then click the Dimension tab. Tip: In the Dimension Map tab, click the regular dimension button. 2. Click the Dimension tab. 3. Click Add Hierarchy and then drag one or more objects from the Available items box to the Hierarchies box. You can define multiple hierarchies for a dimension. The first hierarchy is used as the default, or primary, hierarchy. You can also create an alternate hierarchy by copying a level. Click a level and drag it to the right border of the dimension. You can only copy a level within the same dimension. Tip: In the Dimension Map tab, drag objects from the Project Viewer to the Dimensions box. 4. Click Add Level and then drag one or more objects from the Available items box into the new level. You can also create copies of levels in the Dimension Definition dialog box or in the Dimension Map tab. Click the level and drag it to another position in the hierarchy. All attributes of the level are also copied. You can only copy a level within the same dimension. Tip: In the Dimension Map tab, drag objects from the Project Viewer to the Dimensions box. 5. If you want to use a different item in a level, drag it from the Available items box to the Select a level in the hierarchy control to see the query items box. You are prompted to specify its role. By default, Framework Manager adds the name of the namespace. You can explore or change measures. Tip: In the Dimension Map tab, click Measures, right-click one or more measures, and click the command you want. You can add an item to the business key. Tip: In the Dimension Map tab, click Attributes, right-click the item, and click Key, Include. 80 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 6. If you want to indicate that the keys of the levels above the current level are not necessary to identify the members in this level, select the item and select the Unique Level check box. Do this only if the key values are unique regardless of their context, such as postal code values. 7. Choose the options that you want: Specify roles (p. 83). Embed calculations by clicking Add and then defining the expression (p. 120). To change a calculation that has been embedded in the dimension, in the Dimension Map tab, click Attributes, right-click the query item, and click Edit Expression. Embed filters (p. 122). Test the dimension (p. 86). Edit the SQL and change various options (p. 102). 8. Click OK. 9. To change the default hierarchy for a dimension with multiple hierarchies, do the following: In the Properties pane, click the ellipsis (...) button in the Default Hierarchy box. Select a different hierarchy, and click OK.

Hierarchies for a Regular Dimension

For information about hierarchies for SAP BW metadata, see (p. 145) and (p. 147). A hierarchy is an ordered list of levels or a collection of items. Each query item in a hierarchy must have a unique name. Only a single hierarchy can be defined on a data source regular dimension or any regular dimension that participates directly in a relationship. A model regular dimension can have multiple hierarchies. Multiple hierarchies occur when different structural views can be applied to the same data. The first hierarchy is the primary or default hierarchy. For example, sales staff can be viewed by manager or by geography and can be modeled as a single dimension with two hierarchies.

You cannot use the hierarchies from a single dimension in the same report. If you need both hierarchies in the same report query, such as on opposing axes, you must create a regular dimension for each hierarchy. For example, here is sales staff as two dimensions.

User Guide 81

Chapter 4: Preparing Relational Metadata for Use in Reports Tip: To change the default hierarchy for a dimension with multiple hierarchies, in the Properties pane, click the ellipsis (...) button in the Default Hierarchy box, select a different hierarchy, and click OK.

Balanced Hierarchy
Each path in a balanced hierarchy descends to the same depth. For example, in the following diagram, the highest level is Product Line. Level 2 is Product Type. Level 3 is Products.

Unbalanced Hierarchy
The branches in an unbalanced hierarchy descend to different levels. For example, in the following diagram, the highest level in an organization is the CEO. Level 2 is the vice-presidents and the CEOs executive assistant. The executive assistant does not have subordinates although the vice-presidents do.

An unbalanced hierarchy can also be ragged. In a ragged-unbalanced hierarchy, there are gaps in the levels and the levels descend to different depths.

Ragged and Network Hierarchies

For relational metadata, we recommend that ragged hierarchies and network hierarchies be flattened in the data source.

Levels for a Regular Dimension

A level is a collection of attributes or query items, typically of a common granularity. Each level needs an item that is defined as a key and another item that is defined as a caption. The first level of the hierarchy is automatically defined as the All level. It contains a single root member, which represents the top level of the hierarchy. For example, the All level for the Time dimension is named Time (All). You cannot delete or move the All level. You can change its name, description, and screen tip. If you do not specify the levels of the hierarchy correctly, incorrect aggregation could occur.

82

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Keys for Levels

A key is a query item that uniquely identifies members in a level. For example, Product Number uniquely identifies a product while City, State, and Country are all needed to uniquely identify a city. The key may or may not be contained in a level. Foreign keys are used to relate the measure dimension to its regular dimensions. Each level needs an item that is defined as a key. If a model dimension contains a query item whose data type is BLOB, create a query subject that has determinants and then create a model dimension that is based on the model query subject.

Specify Roles
For information about roles for SAP BW metadata, see (p. 149). Roles define what appears in the member tree in the report authoring tools. Use roles to organize and manage metadata and to determine how to present data to your users. You can also create expressions that refer to roles instead of query items. You must use the roleValue function to refer to a particular role. For example, you want to query against a specific role in a hierarchy but the query item playing that role is different at each level of the hierarchy. A single query can span the different query items at each level. You can also use the roleValue function when you know the role but not the underlying query item. You can assign multiple roles to one query item, but the same role cannot be assigned to different query items in the same level. Default roles are pre-defined for all parent-child hierarchies and for all levels in level-based hierarchies. Most of these roles are not visible in the report authoring tools. The roles that are reserved by Cognos 8 start with an underscore. You cannot define a custom role whose name starts with an underscore. The default roles include the following: _businessKey Represents the key for the level. This role is also used to drill through from one data source to another because the business key should be consistent across your organization. The _businessKey role can be assigned to only one attribute in a level. The Root Business Key property shows the value of the business key for the root member. The root member is an artificial level created for dimensionally modeled relational models. To enable drill-through on conforming dimensions, you must set the Root Business Key property. _memberCaption Presents the caption for a member that will be shown in the report authoring tools. The _memberCaption role is necessary to leverage member functions and to enable dragging and dropping levels in the report authoring tools. _memberDescription Returns the description for a member within a dimension. By default, attributes are included with no role. You can assign attributes to existing roles or you can create custom roles. Each role that you create must have a unique name. You can translate the custom roles in the model.

Steps
1. 2. 3. 4. 5. 6. 7. Click the dimension whose roles you want to define. From the Actions menu, click Edit Definition. Click the Dimension tab. In the Hierarchies box, click the level you want. In the Select a level in the hierarchy control to see the query items box, click a query item. Under Role, click the ellipsis (...) button. Choose whether to use a role defined by Framework Manager or to create a new role:

User Guide 83

Chapter 4: Preparing Relational Metadata for Use in Reports To use a role defined by Framework Manager, click the Default Roles tab, and select a role. To create a role, click the Custom Roles tab, and click Add. 8. Click Close. 9. Click OK. You can also use the Dimension Map tab to define roles. Click Attributes, right-click the query item, and click Edit Roles.

Create a Measure Dimension

For information about creating a key figures dimension for SAP BW metadata, see (p. 150). A measure dimension is a collection of facts such as Quantity Sold or Price. You can create a measure dimension from one or more query subjects that have a valid relationship between them. When used in a report or analysis, the measure dimension shows the value of the query item such as a name or number, or shows null, zero, or invalid. Measure dimensions are related to each other through the regular dimensions. To create reports that fully compare and contrast functional areas, you may need to use more than one measure dimension in a report. Only measures are visible in the model measure dimension. Query items, such as keys, are hidden. Foreign keys are also shown for data source dimensions and are used to relate the measure dimension to data source regular dimensions or query subjects. You can add value by embedding calculations based on existing business rules, such as Profit Margin. You cannot define hierarchies or levels for a measure dimension. When upgrading from an earlier version of Cognos 8, we recommend that you manually convert query subjects that contain facts to measure dimensions. For information on upgrading, see "Upgrading a Best Practices Model from ReportNet 1.x" (p. 229).

Steps
1. Click a namespace where you want to place the measure dimension. 2. From the Actions menu, click Create, Measure Dimension. Tip: In the Dimension Map tab, click the measure dimension button. 3. Click the Measure Dimension tab. 4. Drag measures from the Model Objects box to the Measures box. 5. Perform the actions that you want. Goal Embed a calculation Action Click Add. You can also right-click a measure and click Add or Edit. Embed a filter Test the measure dimension Convert a measure into a query item Click the Filters tab. Click the Test tab. Right-click the measure and click Convert to Query Item.

6. Click OK. For information about measure dimensions at different levels of granularity, see "Multiple-fact, Multiple-grain Queries" (p. 223) and "Multiple Hierarchies" (p. 227) embedded calculations, see (p. 120)

84

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports embedded filters, see (p. 122) testing the measure dimension, see (p. 86)

Convert a Measure into a Query Item

If you have created a data source measure dimension and want to join it to regular dimensions, you need to create joins. Joins need keys and keys are query items, not measures. The measure that you want to use as a key must be converted into a query item. You can also convert a query item into a measure (p. 119). We recommend that you do not convert measures that are in model measure dimensions.

Steps
1. 2. 3. 4. Double-click the measure dimension that contains the measure. Click the Measure Dimension tab. Right-click the measure and click Convert to Query Item. Click OK.

Define Scope Relationships

A scope relationship defines that measure dimensions and regular dimensions can be related for reporting purposes. If you set the scope relationship for the measure dimension, the same settings apply to all measures in the measure dimension. If data is reported at a different level for the measures in the measure dimension, you can also define a scope relationship for each measure. You can specify the lowest level that the data can be reported on. When you create a measure dimension, Framework Manager creates a scope relationship between the measure dimension and existing regular dimensions that are appropriate for that measure dimension. Framework Manager looks for a join path between the measures of the measure dimension and the attributes of the regular dimensions, starting with the lowest level of detail. If there are too many join paths available, Framework Manager may not be able to automatically create a scope relationships. You must create them manually. Tip: If you want Framework Manager to define the scope relationship, select the measure dimension and the regular dimension, and click the determine scope button. A scope relationship does not define how the underlying data is related; that is the responsibility of join relationships. Join relationships define the physical relationship, and scope relationships define the reporting relationship.

Steps
1. Click the Dimension Map tab. Tip: To view scope relationships highlighted with a background color, click the show scope button. 2. Click one or more measure dimensions. 3. Click the level of the dimension that you want to set the scope to. 4. Click the set scope button. Tip: If you want to remove the scope, select the hierarchy or dimension and click the remove scope button. If you select a hierarchy, you can remove the scope from a specific hierarchy without affecting the scope set in other hierarchies of the dimension. If you select the dimension, all scope from all hierarchies is removed. The scope relationship between the measure dimension and the regular dimension is also removed.

Create a Regular Dimension Based on Existing Objects

You can create a new regular dimension by merging existing objects. These objects can be dimensions, query subjects, or query items.

User Guide 85

Chapter 4: Preparing Relational Metadata for Use in Reports

Steps
1. Select the objects that you want in a dimension. 2. From the Actions menu, click Merge in New Regular Dimension.

Explore Dimensions
For information about exploring SAP BW dimensions, see (p. 152). You can explore a visual representation of the objects that are connected to the query subject or dimension that you select in the Project Viewer. The Context Explorer shows the objects that the selected object is connected to. You can select a connected object and see its references too. You can hide an object in the Context Explorer. You can also change the layout, fit all objects in the Context Explorer, and zoom in and out. You can also use the Dimension Map tab to explore dimensions.

Steps
1. Select one or more objects that you want to explore. 2. From the Tools menu, click Launch Context Explorer. 3. To see the connected objects, click one or more objects and click the appropriate button. Goal View the objects that are related to the selected object. View the immediate references for the objects. Available only for regular dimensions and measure dimensions. View all references for the objects. Available only for dimensions and measure dimensions. 4. If you want to see details about an object, such as its relationships and query items, right-click the object, click Level of Detail, and then select the details that you want to see. Button

Test a Dimension, Query Subject, or Query Set

For information about testing SAP BW metadata, see (p. 152). Testing a regular dimension returns the attributes associated with the hierarchy defined as the default. You can see the results that an object returns by testing it. You can test when creating an object or later on. The objects you can test are dimensions, query subjects, query sets, hierarchies, levels, calculations, and query items. You can test a specific report before publishing a package by selecting and testing the objects that will appear in the report. This makes it easier to debug a model and to verify that the model meets the reporting requirements because you do not need to create and publish packages first. When you test an object, Framework Manager returns sample data. Formatting is not applied to the sample data. If you must test formatting, you must publish the package and view the objects in the report authoring tools. You can change existing test settings to customize the results that the test shows. For example, in addition to other settings, you can control the number of rows returned.

Steps When Creating or Modifying an Object

1. Select the object you want to test. 2. From the Actions menu, click Edit Definition, and click the Test or Query Information tab. The Test Results box is initially empty until you run the query.

86

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports Any result sets that contain Binary Large Objects are shown as [blob]. 3. To run the query and bring back all the test results, click Test Sample. 4. Choose the option that you want. Goal Add a count of the rows Process all records at one time instead of one page at a time Group and total measures Obtain more information about the query results 5. Click OK. Action Click Total Rows. Select the Batch check box. Select the Auto Sum check box. Click the Query Information tab.

Steps to Test a Specific Report

1. Select the object or objects that will appear in the report. 2. From the Tools menu, click Test. A message appears, telling you if the test was successful or if problems were found. 3. To view details about any problem that is found, click the Query Information tab. If you do not see the results of the query in the test window, the data from your data source may exceed the value of the Runtime Limits governor. The query stops at the specified limit, but the test result window does not contain any data. Tip: Set the Runtime Limits governor to zero. When you test a measure dimension, the SQL uses aggregates not the measures. For more information about the Context Explorer, see "Explore Dimensions" (p. 86).

Change the Test Settings

You can customize the tests by changing the test settings.

Steps
1. Select the object that you want. 2. From the Actions menu, click Edit Definition and then click the Test tab or the Query Information tab. 3. Click Options and then click the Test Settings tab. 4. Choose the options that you want. Goal Restrict the number of rows that are returned Action Select the Restrict the maximum number of rows to be returned check box and type the required number of rows Persistence This setting applies to all dimensions, query subjects, and query sets in the model. This setting is saved and used in your next session with any model.

Specify the level of detail

Drag the Level of Information This setting is saved and used in shown in Results Information your next session with this model. slider to the location that represents the amount of detail you require

User Guide 87

Chapter 4: Preparing Relational Metadata for Use in Reports

Goal

Action

Persistence The override values are not saved with the model. This setting is for your current session only.

Temporarily override In the Session Parameters box, session parameters click Set. The Session Parameters dialog box appears. Apply relevant design mode filters Select the Apply all relevant design mode filters when testing check box. This applies all relevant filters whose usage is set to design mode in another dimension, query subject, or query set. Apply a security filter Change the prompt values In the Security Filters box, click Edit. In The Current Prompt Values box, click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model. 5. Click OK two times. For information about working with dimensions, see (p. 78). working with query subjects, see (p. 89).

This setting is saved and used in your next session with any model.

The prompt values are not saved with the model. This setting is for your current session only.

Modify Multiple Objects at Once

For information about SAP BW metadata, see (p. 154). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order. 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show. 4. Make any changes to the values of the property.

Convert a Regular Dimension into a Query Subject

You can convert a regular dimension into a query subject. The dimension becomes either a data source query subject or a model query subject. You can also convert a query subject into a dimension (p. 101). When using data source dimensions, we recommend that you create all levels that may be necessary for reporting instead of only those levels that are immediately necessary.

88

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports If a dimension has multiple hierarchies, only the default hierarchy is included when you convert the dimension to a query subject.

Steps
1. Click the regular dimension or measure dimension. 2. From the Actions menu, click Convert to Query Subject.

Working with Query Subjects

For information about query subjects for SAP BW metadata, see (p. 155) A query subject is a set of query items that have an inherent relationship. You use Framework Manager to modify query subjects to optimize and customize the data that they retrieve. For example, you can add filters or calculations. When you change the definition of a query subject, Framework Manager regenerates the associated query items, ensuring that any changes to query subject properties are reflected in all query items for that query subject. There are different types of query subjects in Framework Manager: relational data source query subjects (p. 89) model query subjects (p. 89) stored procedure query subjects (p. 90)

Relational Data Source Query Subjects

Each query subject that is based on relational metadata is defined by an SQL statement that describes how to retrieve data from the data source. Relational data source query subjects directly reference data in a single data source. Framework Manager automatically creates a relational data source query subject for each table and view that you import into your model. For example, you import the Employee detail fact table from the GO Data Warehouse sample database. Framework Manager then creates a query subject using the following SQL statement:
Select * from [go_data_warehouse].EMPLOYEE_DETAIL_FACT

Framework Manager generates query subjects that represent tabular data from the data source. For example, a query subject that references an entire table contains query items that represent each column in the table. If the SQL selects only specific columns, only those columns are represented as query items. Each relational data source query subject can reference data from only one data source at a time. However, the advantage of relational data source query subjects is that you can directly edit the SQL that defines the data to be retrieved. This means that you can insert parameters that control the data that the query retrieves create query subjects based on arbitrary SQL To use multiple data sources for a query subject, use a model query subject that accesses the data source query subjects or other model query subjects. For more information, see "Modifying a Query Subject" (p. 91).

Model Query Subjects

Model query subjects are not generated directly from a data source but are based on query items in other query subjects or dimensions, including other model query subjects. By using model query subjects, you can create a more abstract, business-oriented view of a data source. Usually, model query subjects are created in the business view, not the import view. Because model query subjects are based on the metadata in your model, they let you reuse complex SQL statements that exist in the model reference objects from different data sources in the same query subject

User Guide 89

Chapter 4: Preparing Relational Metadata for Use in Reports If you import a model query subject from another model, the model query subject will not work unless you also import the data source query subjects that the model query subject references. If you add calculations or filters to a model query subject, Cognos 8 must go to the data source instead of simply accessing the model. If you want to edit the SQL, you must copy the SQL for the model query subject from the Query Information tab and paste it into a new data source query subject. For more information, see "Create a Model Query Subject Based on Existing Objects" (p. 95) "Modifying a Query Subject" (p. 91) "Organizing the Model" (p. 136)

Stored Procedure Query Subjects

Stored procedure query subjects are generated when you import a procedure from a relational data source. Framework Manager supports only user-defined stored procedures. System stored procedures are not supported. The procedure must be run in Framework Manager to get a description of the result set that the procedure may return. The stored procedure must return a single uniform result set. Cognos 8 supports only the first result set that is returned. If the procedure could conditionally return a different result set, the format must be consistent with the one used to define the metadata in Framework Manager. Each result set must return the same form, such as the same number, types, and names of columns. Overloaded signatures are supported by Cognos 8, but each procedure must be defined as a uniquely named procedure with a separate query subject for each result set. Output parameters are not supported. After you import or create a stored procedure query subject, it appears as a broken object. You must run it to validate the underlying stored procedure and specify the projection list. Static metadata often does not exist for the stored procedure in the relational data source that describes what a result set may look like. The result set may be known only at run time. When a stored procedure is updated in the data source, running the stored procedure in Framework Manager updates the query subject using the newly generated query items. Sometimes functions are imported as stored procedure query subjects. Review the stored procedure definition to determine what the procedure expects to be passed and what it attempts to return. Edit and test each stored procedure query subject that you think could be a function. If the test fails, the query subject is a function and must be deleted.

Stored Procedures from Informix Data Sources

If you have stored procedures from Informix Dynamic or Parallel Server data sources, you must edit the parameters. We recommend that you refer to the original source of the stored procedures to ensure that they are mapped correctly. Informix 7.x and 8.x provide only the name of the stored procedure to Framework Manager. You must provide all parameters, such as the parameter name, data type, mode, size, precision, scale, and value so that a result set can be obtained. Informix 9.x provides metadata for stored procedures and user defined functions with default parameter values. Check all parameters before using them, especially the mode attribute. Informix functions are imported as stored procedures. After you import them, you must change them to functions by clicking the f(x) button in the Edit Definition dialog box. This button is enabled only for Informix functions. For more information, see "Modify a Stored Procedure Query Subject" (p. 94).

Create a Query Subject

For information about creating query subjects for SAP BW metadata, see (p. 155) For relational metadata, you can create the following types of query subjects: 90 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports Relational data source query subjects directly reference data in a single data source (p. 89). Model query subjects are based on metadata that exists in your model (p. 89). Stored procedure query subjects are generated from the stored procedures in a relational data source (p. 90).

You can also create a new model query subject by merging existing query subjects and query items (p. 95).

Steps
1. 2. 3. 4. Select the namespace folder and, from the Actions menu, click Create, Query Subject. In the Name box, type a name for the new query subject. Select the type of query subject that you want to create, and click OK. Do one of the following: If the Query Subject Definition dialog box appears, add items to the model query subject (p. 91). If the New Query Subject wizard appears, complete all the steps in the wizard. To ensure that the data source is uniquely identified for a data source query subject, do not exit the wizard before the Finish button appears. You can then modify the data source query subject (p. 91) or the stored procedure query subject (p. 94).

Modifying a Query Subject

For information about modifying query subjects for SAP BW metadata, see (p. 155). After importing or creating a data source or model query subject, you can modify it to better suit your users requirements. You can Add items to the query subject (p. 91).

Specify determinants (p. 92). Embed calculations (p. 120). Embed filters (p. 122). Test the query subject (p. 98). If required, convert it into a dimension (p. 101). If required, edit the SQL and change various options (p. 102).

You can also modify stored procedure query subjects (p. 94).

Add Items to the Query Subject

For information about adding items to SAP BW query subjects, see (p. 155). You can add any combination of objects to a query subject, such as query items, other query subjects, or dimensions. You can add stand-alone calculations and filters, and you can also embed calculations and filters in the query subject.

Steps
1. Select the query subject that you want to add items to. 2. From the Actions menu, click Edit Definition. 3. To add items to a data source query subject, click the SQL tab, and from the Available database objects box, drag objects to the SQL box. You can also insert a data source reference, insert a macro, embed a calculation, and embed a filter. 4. To view the system tables from the data source, select the Show System Objects check box. 5. To add items to a model query subject, click the Query Subject Definition tab, and from the Available Model Objects box, drag objects to the Query Items and Calculations box. You can also embed a filter.

User Guide 91

Chapter 4: Preparing Relational Metadata for Use in Reports 6. If you want to test the query subject, click the Test tab. 7. If you want to view the SQL, click the Query Information tab. 8. Click OK. If any modifications invalidated relationships, other query subjects, calculations, or filters, a warning appears. Usage and aggregation property values are regenerated to reflect the changes that you made. 9. Ensure that the Usage and Regular Aggregate properties are set how you want them. You can now organize objects in the Diagram tab. Tip: From the Diagram menu, click Auto Layout. You can also control the model area that is visible in the diagram. Tip: Click and hold the overview button in the bottom right corner and drag the pointer over the diagram. For information about testing the query subject, see (p. 98) usage and aggregation property values, see (p. 113) macros, see (p. 129)

Specify a Determinant
A determinant is the set of query items that can be used to uniquely identify a set of data. Determinants are imported based on key and index information in the data source. We recommend that you always review the determinants that are imported. Determinants are used only with query subjects. Use a determinant when you want to do any of the following: Add information about functional dependencies between columns to avoid double-counting. Specify the granularity of a denormalized query subject to control grouping and double-counting when using model dimensions. For example, some facts join to time on month and some facts join to time on day. Specify determinants for time to clearly capture the functional dependency between month and day to prevent double-counting for those facts that join at the month key. Uniquely identify the row of data when retrieving text blob data from the data source. Override the determinants imported from the data source that conflict with relationships created for reporting. For example, there are determinants on two query subjects for multiple columns but the relationship between the query subjects uses only a subset of these columns. Modify the determinant information of the query subject if it is not appropriate to use the additional columns in the relationship. Determinants are processed in the order in which they are saved in the model. You can change the order of the determinants. If a query subject has more than one determinant, the first one that covers all the requested items is used. However, if a determinant has the Uniquely Identified check box selected, only that determinant is used. If two determinants have the Uniquely Identified check box selected, the first determinant is used. If you defined a determinant as unique and you selected the Group By check box, grouping is applied after the determinants are processed. The Group By clause is used in the generated SQL, which enables aggregate functions in the data source to be used in Cognos 8. If you have multiple determinants with Uniquely Identified check box selected, only the Group By setting of the first determinant is used. This is because the processing of determinants stops at the first determinant with Uniquely Identified check box selected. Data source query subjects are imported with determinants defined for them. These default determinants are generated based on keys and indexes in the data source. Model query subjects do not have determinants defined for them automatically. If determinants are needed, you must define them manually. Stored procedure query subjects do not have determinants. You cannot use determinants with user-entered SQL. 92 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Steps
1. Click the query subject you want and, from the Actions menu, click Edit Definition. 2. Click the Determinants tab. 3. Choose the action that you want. Goal Action

Add a query item as a determinant Select the query item from the Available items box and click Add. Specify that the selected query item Select the Uniquely Identified check box. is the lowest level of the hierarchy Do this only if the data in this item is unique for every and should be used as the unique row in the underlying data source. identifier Control aggregation and grouping in the physical data source Select the Group By check box. Use the Group By check box for all levels whose data is not unique. If aggregation on an associated attribute is required, the key defined for the determinant should be used in a Group By clause in the query. Also, if an attribute of a Group By level is included in a query, a Minimum aggregate function may be used to ensure that the value is unique in the query. Drag one or more query items from the Available items box to the Key box. Drag query items from the Available items box to the Attributes box. If a determinant defines attributes, all query items in the query subject must be associated with the determinant and defined as either a key or an attribute. You can have a determinant with no attributes defined for it. Framework Manager uses this type of determinant to indicate which query items are indexed. Change the order of the determinants Use the arrow buttons. Determinants are processed in the order in which they are saved in the model.

Define a key Identify which query items users must report on

4. Click OK. For more information, see "Defining Dimensions and Determinants" (p. 222) and "The SQL Generated by Cognos 8" (p. 237).

Determinants and SQL Generation

It is important to understand the effect that determinants have on the SQL that is generated. Determinants affect the grouping and aggregation of data, including other query subjects that have relationships with the query subject as well as the query subject itself. For example, consider the following information. Each Product Line contains many occurrences of Product Type. Each Product Type contains many occurrences of Product. For Product, Product Key is a surrogate key and Product Number is a business key that is used as an attribute. Data joined on Product Key is aggregated correctly when reported by Product Line or Product Type or both. Determinant Product line Key Product line code Group By Yes Uniquely Identified Attributes Product line User Guide 93

Chapter 4: Preparing Relational Metadata for Use in Reports

Determinant Product type Product

Key Product type code Product key

Group By Yes

Uniquely Identified

Attributes Product type

Yes

Cost Margin Product name Product number

Modify a Stored Procedure Query Subject

After you import or create a stored procedure query subject, you can modify it. To avoid inconsistencies, the modified query subject should return the same result set structure as the original stored procedure. Framework Manager supports only user-defined stored procedures. System stored procedures are not supported. There are different types of stored procedures: Data Query Issues a read-only transaction Data Modification Writes a record to the data source. Warning: Testing a data modification stored procedure results in data being written to the data source. You cannot roll back transactions to the data source in Framework Manager. If undesired data is written to the data source as a result of testing the stored procedure, a rollback can be done by the database administrator if the data source is configured to support it.

Steps
1. Select the stored procedure query subject that you want to modify. 2. From the Actions menu, click Edit Definition, and click the Definition tab. 3. Choose the action that you want. Goal Use a different stored procedure Change the type of the stored procedure Change which data source the stored procedure is in Action In the Stored Procedure Name box, type the name of the stored procedure. From the Type box, select Data Query or Data Modification. Click the ellipsis (...) button next to the Data Source box. When you import a stored procedure, a new data source is created. You can point to the original data source and delete the new one. Edit an argument Click the argument and click the ellipsis (...) button. The Syntax box in the Query Subject Definition dialog box shows the correct syntax to use. Generate the projected query items Click the Test tab. 4. Click OK. Framework Manager runs the stored procedure and, if the query subject returns a result set, validates the query subject.

94

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports If the stored procedure does not return a result set, the query subject becomes an invalid query subject if saved in the model. If the invalid query subject is included in the published package, the invalid query subject cannot be used in a report. 5. Ensure that the Usage and Regular Aggregate properties are set correctly for each newly created query item. For example, a query item may be set as a fact when it is an identifier. You can update the stored procedure query subject if the data source changes (p. 101). For more information, see "Test a Query Subject, Query Set, or Dimension" (p. 98).

Example - Use Prompts with a Stored Procedure

Report authors can set stored procedure variables in reports if you define prompts for these variables in Framework Manager.

Steps
1. Create a stored procedure query subject that uses the sp_FIND_ORDER_DATE stored procedure. The Query Subject Definition dialog box appears. 2. On the Definition tab, select the @order_number argument, and click the ellipsis (...) button. 3. In the Value box, type the following macro syntax and then click OK: #(prompt('Order Number','integer'))# Note: Framework Manager removes anything that is outside the number signs when running the macro. 4. To test the prompt for the variable, click the Test tab, and then click Test Sample. The Prompt Values dialog box appears. 5. In the Name column, click Order Number. 6. In the Value field, type 1234 and click OK. One record is returned, showing the date for Order Number 1234. Framework Manager uses this value for the duration of the current session or until you clear the prompt value. 7. Click OK.

Create a Model Query Subject Based on Existing Objects

For information about SAP BW model query subjects, see (p. 156). You can select existing model objects and merge them into a new model query subject. This means that you can reuse existing metadata to quickly create query subjects. The objects that you can merge include relational data source query subjects and their shortcuts model query subjects and their shortcuts query items, filters, and calculations in model and data source query subjects relationships and relationship shortcuts between model and data source query subjects You can merge any number of the same type of objects into a new query in a single operation. The merge always creates a new model query subject. Framework Manager generates the name of the new query subject by appending the name of the first query subject to the name of the last query subject. A unique number is appended to duplicate query item names. You are prompted to re-create any existing relationships between the original query subjects and query subjects that are not included in the merge. However, to avoid self-joins, any relationship that exists between the query subjects being merged is ignored. When you merge query items, only the relationships that the items participate in are replicated. The new query subject contains any filters that exist in the original query subject.

User Guide 95

Chapter 4: Preparing Relational Metadata for Use in Reports

Steps
1. Ctrl+click the objects that you want to merge into a single query subject. 2. From the Actions menu, click Merge in New Query Subject. If the query subjects are joined to other query subjects, you are prompted to re-create relationships with the new query subject. 3. If prompted to re-create relationships, click Yes.

Explore Query Subjects

For information about exploring SAP BW query subjects, see (p. 156). You can explore a visual representation of the objects that are connected to the query subject or dimension that you select in the Project Viewer. The Context Explorer shows the objects that the selected object is connected to. You can select a connected object and see its references too. You can hide an object in the Context Explorer. You can also change the layout, fit all objects in the Context Explorer, and zoom in and out. You can also use the Dimension Map tab to explore dimensions.

Steps
1. Select one or more objects that you want to explore. 2. From the Tools menu, click Launch Context Explorer. 3. To see the connected objects, click one or more objects and click the appropriate button. Goal View the objects that are related to the selected object. View the immediate references for the objects. Available only for regular dimensions and measure dimensions. View all references for the objects. Available only for dimensions and measure dimensions. 4. If you want to see details about an object, such as its relationships and query items, right-click the object, click Level of Detail, and then select the details that you want to see. Button

Create a Query Set

For information about creating query sets for SAP BW metadata, see (p. 157). A query subject can be defined using the set operations of union, intersect, or except. You define a query set to merge, compare, or equate similar data from different sources. Query sets are useful when modeling data from disparate systems. There are many reasons for creating a query set. A query set may be needed to create a conformed dimension across disparate sources. Or, you may want to compare the contents of two tables to determine whether the tables contain the same data; this is common in test environments. Or, you may want to compare tables with nulls. Or, you want to handle a fact-to-fact relationship. A query set can consist of only two query subjects. You can create a query set that merges two other query sets together. A query set can contain all the rows of two query subjects (union operation) For example, your company recently acquired another company and you need a complete list of all customers. only the rows that are shared between the query subjects (intersect operation) For example, you want to find out which staff members are also managers. only the rows that are different between the query subjects (except operation) 96 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports For example, you want to highlight the differences between where your products were sold this year and ten years ago. Relationships between the two query subjects in the query set and other query subjects are not included in the query set. The names of the items in the projection list default to the items assigned to the first query subject in the set operation. Not all data types are supported. Generally, sets are not permitted on BFILE, BLOB, CLOB, LONG, and VARRAY data types, or on nested table columns. Reports show different results depending on which operator is used. For example, you have two query subjects with the names of various employees. One contains these rows: Jane, John, John, Patrick. The second contains these rows: Jane, John, John, Michael, Michael. You create a query set. Operator Union Intersect Except Union All Intersect All Except All Result Jane, John, Michael, Patrick Jane, John Michael, Patrick Jane, Jane, John, John, John, John, Michael, Michael, Patrick Jane, Jane, John, John, John, John Michael, Michael, Patrick Notes All items are shown. Values are not duplicated. Items in common are shown. Values are not duplicated. Items that are not common are shown. Values are not duplicated. All items are shown. Values are duplicated. Items in common are shown. Values are duplicated. Items that are not common are shown. Values are duplicated.

Steps
1. Select two query subjects that meet these requirements: Each query subject must have the same number of columns. Columns must be in the same order. Columns must have the same or similar data types. The data types do not need to be exactly the same if those in the second result set can be automatically converted by the data source to data types compatible with those in the first result set. For example, one query subject contains country data and uses int as the data type. Another query subject contains country data and uses smallint as the data type. Framework Manager imports these query subjects as int16 and int32 and performs a set operation. 2. From the Actions menu, click Define Query Set. 3. Click the Definition tab. 4. In the Name box, give the query set a name. The Query Subject boxes show the order that the query subjects will appear in the Select clause. The order in the Select clause could be important if you want a specific set of column names (aliases) that appears in only one of the query subjects. If the order is incorrect, cancel this query set and start again. For union and intersect, the order of the query subjects does not matter. You can change the order and receive the same answer. For except, the order of the query subjects does matter.

User Guide 97

Chapter 4: Preparing Relational Metadata for Use in Reports 5. Use the Operator box to define how the rows of the query subjects are combined. Option Union Intersect Except Description Retrieves all unique rows from both sets. Duplicates are removed. Retrieves rows that are common between the query subjects. Retrieves rows that are not common between the query subjects.

6. Choose the action that you want. Goal Create a Union All, Intersect All, or Except All operation Action Clear the Remove Duplicate Row check box.

Work with the calculations that are Click the Calculations tab. embedded in the query subjects You can add or edit the calculations and change the order of the calculations. Work with the filters that are embedded in the query subjects Click the Filters tab. You can add or edit the filters, change the order of the filters, and change the usage of filters. Click the Test tab.

Test the query set 7. Click OK.

For information about embedded calculations, see (p. 120) embedded filters, see (p. 122) determinants, see (p. 92) testing the query set or changing the test settings, see (p. 98)

Test a Query Subject, Query Set, or Dimension

For information about testing SAP BW metadata, see (p. 159). You can see the results that an object returns by testing it. You can test when creating an object or later on. The objects you can test are dimensions, query subjects, query sets, hierarchies, levels, calculations, and query items. You can test a specific report before publishing a package by selecting and testing the objects that will appear in the report. This makes it easier to debug a model and to verify that the model meets the reporting requirements because you do not need to create and publish packages first. When you test an object, Framework Manager returns sample data. Formatting is not applied to the sample data. If you must test formatting, you must publish the package and view the objects in the report authoring tools. You can change existing test settings to customize the results that the test shows. For example, in addition to other settings, you can control the number of rows returned.

Steps When Creating or Modifying an Object

1. Select the object you want to test. 2. From the Actions menu, click Edit Definition, and click the Test or Query Information tab. The Test Results box is initially empty until you run the query. Any result sets that contain Binary Large Objects are shown as [blob]. 3. To run the query and bring back all the test results, click Test Sample.

98

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 4. Choose the option that you want. Goal Add a count of the rows Process all records at one time instead of one page at a time Group and total measures Obtain more information about the query results 5. Click OK. Action Click Total Rows. Select the Batch check box. Select the Auto Sum check box. Click the Query Information tab.

Steps to Test a Specific Report

1. Select the object or objects that will appear in the report. 2. From the Tools menu, click Test. A message appears, telling you if the test was successful or if problems were found. 3. To view details about any problem that is found, click the Query Information tab. If you do not see the results of the query in the test window, the data from your data source may exceed the value of the Runtime Limits governor. The query stops at the specified limit, but the test result window does not contain any data. Tip: Set the Runtime Limits governor to zero. For more information about the Context Explorer, see "Explore Query Subjects" (p. 96).

Change the Test Settings

You can customize the tests by changing the test settings.

Steps
1. Select the object that you want. 2. From the Actions menu, click Edit Definition and then click the Test tab or the Query Information tab. 3. Click Options and then click the Test Settings tab. 4. Choose the options that you want. Goal Restrict the number of rows that are returned Action Persistence

This setting applies to all Select the Restrict the dimensions, query subjects, and maximum number of rows to be returned check box and type query sets in the model. the required number of rows This setting is saved and used in your next session with any model. Drag the Level of Information This setting is saved and used in shown in Results Information your next session with this model. slider to the location that represents the amount of detail you require The override values are not saved with the model. This setting is for your current session only.

Specify the level of detail

Temporarily override In the Session Parameters box, session parameters click Set. The Session Parameters dialog box appears.

User Guide 99

Chapter 4: Preparing Relational Metadata for Use in Reports

Goal Apply relevant design mode filters

Action Select the Apply all relevant design mode filters when testing check box. This applies all relevant filters whose usage is set to design mode in another dimension, query subject, or query set.

Persistence This setting is saved and used in your next session with any model.

Apply a security filter Change the prompt values

In the Security Filters box, click Edit. In The Current Prompt Values box, click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model. The prompt values are not saved with the model. This setting is for your current session only.

5. Click OK two times. For information about setting governors, see (p. 194). security filters, see (p. 200). temporarily overriding session parameters, see (p. 128). changing prompt values, see (p. 125). working with dimensions, see (p. 78). working with query subjects, see (p. 89).

Modify Multiple Objects at Once

For information about modifying SAP BW objects, see (p. 161). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order. 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show. 4. Make any changes to the values of the property.

Validate a Query Subject

For information about validating SAP BW query subjects, see (p. 161). After you change the definition of a query subject by adding new query items or changing the parameters of a procedure, you can validate the definition of the query subject without having to open the Query Subject Definition dialog box. You can also validate a query subject when the definition of query subjects that it depends on changes. The Evaluate command completes an exhaustive check of all query subjects and ensures that they can run.

100

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports What happens in the evaluation process depends on the type of query subject selected. Type of query subject Relational data source query subject Evaluation process A request based on the derived items is sent to the data source. The list of data source references is updated. The physical attributes, such as data type, are updated as needed. Model query subject based A request based on the derived items is sent to the data source. on relational metadata The cached SQL, if available, is updated. The physical attributes, such as data type, are updated as needed. Stored procedure query subject A request based on the latest parameters of the stored procedure is sent to the data source. The list of derived query items is updated. You can also update the query subject (p. 101), if it is from a relational data source, or synchronize the entire project (p. 55).

Steps
1. Select the query subject that you want to evaluate. 2. From the Tools menu, click Evaluate Object. If you changed the Regular Aggregate property to unsupported, the property is reset when you evaluate the query subject. If the property is set to any other value, the property is not changed.

Update Query Subjects

If you are using a relational data source, you can choose to update only the query subjects instead of performing a full project synchronization. You must perform a project synchronization to synchronize changes in a third-party data source. The query subject is updated based on the definition in the data source. When you update a query subject, new metadata is fetched from the data source and query items are re-synchronized. You can also evaluate the query subject, if it is from a relational data source (p. 100). You cannot use the Update Object command for model query subjects.

Steps
1. Select one or more query subjects. 2. From the Tools menu, click Update Object. Tip: You can instead open the Query Subject Definition dialog box and click OK.

Convert a Query Subject into a Dimension

You can convert a query subject into a regular dimension or a measure dimension when you want to use features associated with dimensions, such as defining hierarchies and levels. A data source query subject becomes a data source dimension. A model query subject becomes a model dimension. You can also convert a dimension into a query subject (p. 88). If the query subject has determinants specified for it, the determinants are used to define the levels of the dimension that you are creating. The determinants form one hierarchy. You cannot use determinants to create separate hierarchies for the dimension. You must create the separate hierarchies for the dimension after converting the query subject. You cannot convert query sets, stored procedure query subjects, or SAP BW query subjects to dimensions.

User Guide 101

Chapter 4: Preparing Relational Metadata for Use in Reports

Steps
1. Select the query subjects that you want to convert. 2. From the Actions menu, click Convert to Regular Dimension or Convert to Measure Dimension.

Edit the SQL

SQL is the industry-standard language for creating, updating, and querying relational database management systems. When you edit the definition of a relational data source query subject (p. 89), you can use Cognos SQL (p. 104) native SQL (p. 105) pass-through SQL (p. 105) If you want to edit the SQL of a model query subject, you must copy the SQL for the model query subject from the Query Information tab and paste it into a new data source query subject. Do not edit the SQL if you want the model query subject to reference multiple data sources. Changing the alias of a column regenerates the query item that represents that column. Any modifications that you made to the query item are not retained because Framework Manager considers it a new query item. You can add comments to the SQL by using /* before the comment and */ at the end. Here is an example:
select country /* this is a multiline comment another line another line */

Steps
1. 2. 3. 4. Click the data source query subject that you want to change. From the Actions menu, click Edit Definition. Click the SQL tab, and drag objects into the SQL box or type in the SQL you want. Click OK.

Change the Type of SQL

When choosing the type of SQL in which to generate a data source query subject, you must weigh the following factors and decide which are most important. Type Cognos SQL Advantage Cognos SQL improves query subject performance; for example, by removing unused elements at query time. SQL works on any supported database. Native SQL Performance is optimized across all related query subjects. You cannot use SQL that the data source does not support for subqueries. Disadvantage You cannot enter non-standard SQL.

You can use SQL that is specific to your The SQL may not work on a different database type. database. PassYou can enter any SQL supported by the There is no opportunity for Framework Through database. Manager to automatically optimize SQL performance. The SQL may not work on a different data source.

102

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports Note that you cannot change the type of SQL for query subjects that are based on OLAP data sources.

Prerequisites for Changing to Native SQL

If you change an existing query subject to native SQL, you must first ensure that the SQL reflects the rules that apply to the native data source so that your query runs properly. You must do the following: Edit existing table names. Cognos SQL uses a two-part structure to name query subjects. For example, [gosales].[ProductLine] means that the ProductLine query subject comes from the gosales database. Therefore, when you switch to native SQL, you must ensure that all table names include the parent elements required by the data source vendor. For information about naming conventions, see "Naming Conventions for Objects in a Project" (p. 19). Ensure that the SQL is valid for subqueries. Framework Manager processes native SQL query subjects as subqueries. For example, here is a Cognos SQL query subject:
Select P.ProductName, P.Margin From Product P

If you change it to native SQL, Framework Manager generates the following statement:
Select oracle_plain.ProductName as Productname, oracle_plain.Margin as Margin From (GOSALES1_OR_92_WE...SELECT P.PRODUCTNAME, P.MARGIN FROM PRODUCT P} )oracle_plain

Therefore, you must ensure that the query subject adheres to additional database restrictions that are imposed on subqueries, such as not using the With clause. Pass-through SQL does not have the same restrictions. However, the fact that native SQL is processed as part of a larger query improves its performance. To test native SQL using a query tool, such as Oracle's SQL*Plus, you must place the SQL in the From clause of a Select statement. For example, you can use the following syntax in a query tool:
Select * from (<Native SQL>) T1

Assign aliases to derived columns. Assign alias names to any columns whose values are calculated. Here is an example:
SELECT Length(Country) as LGTH FROM Country

Insert double quotation marks around alias names. Changing the SQL type of a query subject can change the case of alias names. When this happens, any query subject that references the changed query item becomes invalid. To ensure that there is no case change, insert double quotation marks around the alias, such as
Select COUNTRY as "test" from COUNTRY

If a data source query subject contains a macro in the projection list (Select clause) of the SQL statement, specify an alias in the SQL that matches the Column Name property of the query item. An error could occur because the macro evaluates to a column name that is different from the Column Name property of the corresponding query item. The result is that the system is unable to locate the item in the projection list. Projection lists are static. Assigning an alias ensures that the name of the item in the projection list remains constant, as the results of evaluating the macro change. For example, the following query contains a session parameter, runLocale, whose value specifies which column the query retrieves:
Select

User Guide 103

Chapter 4: Preparing Relational Metadata for Use in Reports

#$ColumnMap{$runLocale}# as CountryNameAlias From [GoSales].Country

Note that the number sign (#) is reserved for macros. Framework Manager removes anything that is outside the number signs when running the macro.

Steps
1. Click the query subject that you want to change. 2. From the Actions menu, click Edit Definition, and then click the Query Information tab. The Test Results box is initially empty until you run the query. 3. Click Options, and then click the SQL Settings tab. 4. Use the SQL Type list to change the type of SQL. If you are changing the type to native SQL, see the checklist above to ensure that the SQL reflects the rules that apply to the native data source. 5. Click OK. 6. If you want to see the SQL, click Test Sample. 7. If you want to see the actual query, click Query. 8. If you want to see the xml that Cognos 8 uses, click Response. 9. Click OK.

Cognos SQL
By default, Framework Manager uses Cognos SQL to create and edit query subjects. Cognos SQL adheres to SQL standards and works with all relational and tabular data sources. Framework Manager generates the most optimized SQL possible. In this way, Cognos SQL is preferable. Because query subjects in Framework Manager are similar to views in databases, the SQL for each query subject must conform to the SQL standards that apply to views. For example, you must assign aliases to any column that is empty or whose name is not unique. This level of conformance means that Cognos SQL behaves more consistently than vendor-specific SQL, which does not adhere to SQL standards. In general, using Cognos SQL is preferable because you can create query subjects that can contain metadata from multiple data sources have fewer database restrictions interact more effectively with Cognos applications

Constructs of the SQL Standard

If the data source supports it, you can use the With clause with Cognos SQL. The With clause is used to generate more readable SQL and to let the data source generate a more optimal plan for data retrieval. The data source can more easily detect the cases where the same tables must be scanned and can then resolve these as an inline view or temporary table. By default, Framework Manager uses the common table constructor from the SQL standard when the Use With clause when generating SQL governor is set. Use the With clause for better query performance if the request is restricted to functionality supported by the underlying data source software. When a request uses functionality that is not supported by the data source, using the With clause may cause additional decomposition of the query, which can lead to degraded performance. In this case, not using the With clause may generate a better set of queries to the underlying data source. Here is an example of Cognos SQL using derived tables:
SELECT * FROM (SELECT SNO C1, AVG(QTY) C2, COUNT(*) C3 FROM SUPPLY GROUP BY SNO) T1, (SELECT MAX(QTY) C1 FROM SUPPLY) T2

The following shows how Cognos SQL turns the above example into a With clause:
WITH T1 AS (SELECT SNO C1, AVG(QTY) C2, COUNT(*) C3 FROM SUPPLY GROUP BY SNO), T2 AS (SELECT MAX(QTY) C1 FROM SUPPLY) SELECT *FROM T1, T2

104

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports Do not use the With clause for recursive processing. For more information about the With clause, see "Set Governors" (p. 194). Cognos continues to improve data type checking and SQL validation. Because of this and because not all vendors are completely compliant with the SQL standard, invalid or ambiguous SQL expressions that previously were passed to the data source will no longer be passed down. If you have an expression that returns a data type not specified by the SQL standard, we recommend that you pass the expression to the data source by using the syntax {expr}. Report authors should use the same technique.

Native SQL
Native SQL is the SQL that the data source uses, such as Oracle SQL. Use Native SQL to pass the SQL statement that you enter to the database. Cognos 8 may add statements to what you enter. You can not use native SQL in a query subject that references more than one data source in the project. SQL specified in Framework Manager and processed by the database, whether native or pass-through, must be completely self-contained. It must not reference anything outside that SQL, such as database prompts, variables, or native formatting that would normally be supplied by the calling application. If you are comfortable working with a native SQL version, you may want to use it for query subjects that are based on a single data source. By doing so, you can use keywords that are not available in Cognos SQL, and copy and paste SQL from another application into Framework Manager. When the query is generated, Framework Manager combines the SQL of each query subject that uses a given data source connection into a single query. This helps improve the performance of the query. However, because the SQL is being generated as a series of subqueries, native SQL queries must adhere to any restrictions that their database vendor places on derived tables. Here is an example of native SQL that returns a list of employees and managers:
SELECT lpad(' ', (level-1)* 4) || ename EMP_CHART, level, empno, ename, job, mgr FROM emp CONNECT BY PRIOR empno = mgr AND deptno not in (20,30) START WITH mgr IS NULL ORDER BY level, job

Pass-through SQL
Use pass-through SQL when the SQL statement that you enter is not valid inside a derived table. Pass-through SQL lets you use native SQL without any of the restrictions that the data source imposes on subqueries. This is because pass-through SQL query subjects are not processed as subqueries. Instead, the SQL for each query subject is sent directly to the data source where the query results are generated. Because each query subject is sent to the data source as a separate statement rather than being optimized by Framework Manager, performance is slower. Therefore, in choosing between native SQL and pass-through SQL, you must decide which is more important: performance or using SQL that is not permitted in a subquery. Generally, you should use pass-through SQL only if you must create a query subject that contains constructs that are specific to a data source and that cannot be used inside a derived table, such as in a With or OrderBy clause.

User Guide 105

Chapter 4: Preparing Relational Metadata for Use in Reports SQL specified in Framework Manager and processed by the database, whether native or pass-through, must be completely self-contained. It must not reference anything outside of that SQL, such as database prompts, variables, or native formatting that would normally be supplied by the calling application. For example, here is a systems-oriented report that contains the system date:
SELECT TO_CHAR(SYSDATE, 'DAY, DDTH MONTH YYYY') FROM SYS.DUAL

Note that the number sign (#) is reserved for macros and that column names must be unique. Framework Manager removes anything that is outside the number signs when running the macro.

Change How the SQL Is Generated

You can specify how Framework Manager generates the SQL that retrieves data from relational data sources for data source query subjects (p. 89) or model query subjects (p. 89). The SQL Generation type of a query subject can be set to either As View or Minimized. By default, it is set to Minimized. When the generation type is set to Minimized, the generated SQL contains only the minimal set of tables and joins needed to obtain values for the selected query items. When the generation type is set to As View, Framework Manager generates queries that contain the full SQL statement that defined the query subject. Use As View when you want to ensure that the query is run as a block. The SQL is treated as a view. For example, you want the query to return the same number of rows each time that it is run. The SQL Generation setting has no effect on a query subject with determinants specified for it. Using minimized SQL improves performance, resulting in a query that runs significantly faster. Generating minimized SQL is especially beneficial for query subjects that represent dimension tables. By using a single model query subject to model a dimension, you can benefit from small SQL queries that run significantly faster. For example, the SQL Generation Type of the following query subject is As View. Note that this query subject contains a nested select statement.
select New_Query_Subject.COUNTRYCODE as COUNTRYCODE, New_Query_Subject.EUROINUSESINCE as EUROINUSESINCE from (select CONVERSIONRATE.COUNTRYCODE as COUNTRYCODE, COUNTRY.EUROINUSESINCE as EUROINUSESINCE from "2 - GOSales1 - OLE-DB".GOSALES1.dbo.CONVERSIONRATE CONVERSIONRATE, 2 - GOSales1 - OLE-DB".GOSALES1.dbo.COUNTRY COUNTRY where (COUNTRY.SALESCOUNTRYCODE = CONVERSIONRATE.COUNTRYCODE) ) New_Query_Subject

If you change the SQL Generation Type to Minimized, Framework Manager generates the following simplified SQL:
select CONVERSIONRATE.COUNTRYCODE as COUNTRYCODE, COUNTRY.EUROINUSESINCE as EUROINUSESINCE from "2 - GOSales1 - OLE-DB".GOSALES1.dbo.CONVERSIONRATE CONVERSIONRATE, "2 - GOSales1 - OLE-DB".GOSALES1.dbo.COUNTRY COUNTRY where (COUNTRY.SALESCOUNTRYCODE = CONVERSIONRATE.COUNTRYCODE)

Minimized SQL works best when the returned result sets of each query item are equivalent. If there are records in one column that do not correspond to records in another column, the result of the minimized query produces additional rows. You can avoid this by setting the SQL Generation Type to As View.

106

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports For example, if there are Product Types that are not used by any of the Products and these Product Types all have a common Product Line, a Product Line is reported for which there are Product Types, but for which there are no related Products.

Model Query Subjects and SQL Types

A model query subject that is based on another model query subject may use the logic of the parent query subject instead of its own logic. If the child model query subject uses the Minimized SQL type, it does not use the logic of the parent. If the child model query subject uses the As View SQL type, it uses the logic of the parent. For example, you create a model query subject named Returned Products, which shows all return reasons for all products. When you run Returned Products, you see a list of over 700 items. You then create another model query subject based on Returned Products that is named Return Reasons. This model query subject contains only the Return Reason query item. If the SQL type is set to Minimized, the Return Reasons query subject shows five return reasons when it is run. If the SQL type is set to As View, the Return Reasons query subject uses the logic of the Returned Products query subject and shows over 700 items.

Steps
1. Click the query subject that you want to change. 2. From the Actions menu, click Edit Definition, and then click the Query Information tab. The Test Results box is initially empty until you run the query. 3. Click Options, and then click the SQL Settings tab. 4. Set Generate SQL to As View or Minimized. 5. Click OK. 6. If you want to see the SQL, click Test Sample. 7. If you want to see the actual query, click Query. 8. If you want to see the xml that Cognos 8 uses, click Response. 9. Click OK.

Supporting Multilingual Metadata

For information about multilingual metadata for SAP BW, see (p. 161) For models that are published in multiple languages, you can view and modify model objects in the different languages. We recommend that you handle multilingual support in the import view so that you can reduce the number of query items contained in each dimension and query subject With fewer dimensions, query subjects, and query items, the model is more manageable. simplify maintenance Multilingual work is done in one place instead of in different business views. ensure consistency Languages are set up correctly for all modelers to use. This is particularly important for segmented models. Modelers will not set up languages in their own way. To support multilingual metadata, do the following: Import metadata from multilingual data sources (p. 41).

Define the languages the model supports (p. 108). Define one or more parameter maps that translate the locale used when the report is run into

the language values in the data source (p. 125). Use a macro (p. 129) to dynamically substitute language values from the language lookup table using the runLocale session parameter as the key. Export multilingual properties in translation tables, which translators use to enter the correct text for each language (p. 109). Import the table that contains the translated property values (p. 109). User Guide 107

Chapter 4: Preparing Relational Metadata for Use in Reports

Publish the metadata in the languages you specify (p. 204).

For information about how to enable multilingual modeling, see (p. 110)

Using a Macro to Model Multilingual Data

You can model multilingual data that is stored in multiple tables, columns, or rows, for each supported language. You can use macros with parameter maps and session parameters to create dimensions or query subjects that retrieve data in the preferred language of the person viewing the report. The location of a parameter in the query subject definition depends on the location of multilingual data in the data source. You must have a parameter map in the macro. Data source location A column with a language key in another column Parameter location Select list

Example
Select PRODUCT_TYPE.PRODUCT_TYPE_CODE, PRODUCT_TYPE.PRODUCT_LINE_CODE, PRODUCT_TYPE.PRODUCT_TYPE_#$Language_lookup {$runLocale}# as Product_type from [gosales].PRODUCT_TYPE PRODUCT_TYPE Select PRODUCT.PRODUCT_NAME, PRODUCT_MULTILINGUAL.PRODUCT_NUMBER from [gosales].PRODUCT, [gosales].PRODUCT_MULTILINGUAL Where PRODUCT.PRODUCT_NUMBER = PRODUCT_MULTILINGUAL.PRODUCT_NUMBER and (PRODUCT_MULTILINGUAL."LANGUAGE" = #sq($Language_lookup{$runLocale})#

Rows whose language is identified by a special column, such as LANG

Filter

Add a Language to a Project

For information about adding a language when using SAP BW metadata, see (p. 162). You can add a language to a project at any time. For example, you do this if the values for a language were not translated earlier. When you add a language to a project, Framework Manager generates a new property value for every multilingual property of each object in the project. A multilingual property is any text property that appears in a report, such as Name, Description, and Screen Tip. The new values that Framework Manager assigns to these text properties are a combination of the original property value preceded by the language code. For example, if a dimension is named Country, and you add the Dutch language, Framework Manager inserts a name whose value is (nl)Country. Each project contains two types of language definitions: design language This is the language in which the model was originally created. This value is stored in the model and cannot be changed. It serves as the default language value. active language This is the language in which model content is currently shown. When you open a model, the active language is set to the language in the model that most closely matches the region and language settings of the computer. You can change this value at any time for your current session only. In future sessions, the model continues to open in the design language.

108

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Steps
1. From the Project menu, click Languages, Define Languages. 2. In the Available languages box, select each language you want to add and click the arrow button to move it to the Project languages box. Tip: To remove a language, select it in the Project languages box and click the arrow button to move it to the Available languages box. 3. If you want to change the active language, in the Project languages box, click a language and click Set as Active. 4. Click OK. At the prompt, accept the changes you made to the project. 5. Click OK. Tip: To show multilingual property values in the Properties pane, click the Languages tab.

Export a Translation Table

For information about translation tables and SAP BW metadata, see (p. 163). You can generate and export a translation table to simplify the task of translating model objects. The translation table contains a list of all the text strings defined for multilingual properties, such as Name, Description, and Screen Tip. Translators can then use an external application, such as Microsoft Excel, to type the required information in the table. You can export a translation table as either a comma-separated value file (.csv) or Unicode text file (.txt). You must export the translation table as a Unicode text file if it either contains a non-Latin language or will be imported by a computer with a language setting that is different from your own computer.

Steps
1. Select the objects you want to export. 2. From the Project menu, click Languages, Export Translation File. 3. In the Project Languages box, click the languages you want to export, and click the arrow button to move them into the Languages to be exported box. You must export the design language of the model that will use the translation table. For example, if the translation table will be used in a model that uses French as the design language, you must export French. Framework Manager exports the appropriate locale code for each language you select. If you do not select all the languages to be translated, you must manually enter the language codes in the first row of each new language column in the translation table. 4. In the Model objects to be exported box, select whether you want to export all model objects, or export only preselected objects and their children. 5. Enter the location and name of the translation table. 6. Click OK.

Import a Translation Table

For information about translation tables and SAP BW metadata, see (p. 163). You can add text property values for each language defined in your model by importing translated data from a file. The imported file must be a translation table that was used by translators to enter the required translated values. The translation table must contain the design language of the model that will use the translation table. The translation table can contain a subset of the languages defined for the project.

Steps
1. From the Project menu, click Languages, Import Translation File. 2. In the Project Languages box, click the languages in the translation table, and click the arrow buttons to move them to the Translate from and Translate into box.

User Guide 109

Chapter 4: Preparing Relational Metadata for Use in Reports You must select the design language for this model. 3. In the Apply translation to box, select whether you want to apply the translation to all model objects, or only to preselected objects and their children. 4. Enter the location and name of the translation file. 5. Click OK.

Example - Create a Multilingual Project for Relational Metadata

For an example about SAP BW metadata, see (p. 110). You want to create a model that can be used by English, French, and German report authors. You also want the reporting tool to automatically show metadata in the language required by the report author. In the go_data_warehouse sample, you need to do the following: Translate the metadata. Use macros to create a multilingual project. You can modify the dimensions and query subjects to show multilingual content by using the Language_lookup parameter map and the runLocale session parameter.

Steps
1. Open the go_data_warehouse project. 2. Ensure that English, French, and German are supported languages: From the Project menu, click Languages, Define Languages. Ensure that the Project languages pane contains English, French, and German. In the Project Viewer pane, click a query item and, in the Properties pane, click the Languages tab. For the name, description, and tool tip text, you see one entry for each language. 3. Export all the languages and objects in the project to a comma-separated value file (.csv) named GOSLDW-ML.csv. From the Project menu, click Languages, Export Translation File. In the Project Languages box, Ctrl+click English, French, and German, and click the top arrow to move them to the Languages to be exported box. In the Export languages to this file box, enter the location of GOSLDW-ML.csv. 4. Open the GOSLDW-ML.csv file in Microsoft Excel, and translate the strings. Note that each column represents a given language, and the file contains only the text strings that exist in the model. 5. In Framework Manager, import the translated file: From the Project menu, click Languages, Import Translation File. In the Project Languages box, move French and German into the Translate into box. In the Import translation table from this file box, enter the location of GOSLDW-ML.csv. 6. In the Project Viewer, double-click the Language_lookup parameter map. Note that the keys match the possible values for the runLocale session parameter, which identifies the language of the current user. These keys are mapped to the language values that are defined in the go_data_warehouse database. 7. Ensure that the parameter map contains the following information. Key de en fr Value DE EN FR

110

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 8. Select an object that contains multilingual columns, such as the Order method dimension, and, from the Actions menu, click Edit Definition. The language identifier that was appended to the query item name is replaced by a parameter map and the runLocale session parameter:
Select ORDER_METHOD_DIMENSION.ORDER_METHOD_KEY, ORDER_METHOD_DIMENSION.ORDER_METHOD_CODE, ORDER_METHOD_DIMENSION.ORDER_METHOD_#$Language_lookup{$runLocale} # AS ORDER_METHOD from [go_data_warehouse].ORDER_METHOD_DIMENSION

9. To preview the results, click the Test tab and then click Test Sample. 10. From the Project menu, click Session Parameters and change the runLocale session parameter value to fr. 11. Test the Order method dimension again to view the results.

Modifying the Properties of Query Items

For information about query items for SAP BW metadata, see (p. 164). A query item is the smallest piece of the model that can be placed in a report. It represents a single instance of something, such as the date that a product was introduced. For relational metadata, you can modify the properties of query items by setting Usage and Regular Aggregate properties (p. 113) to reflect the intended use of the query item formatting query items (p. 117) to control how data appears in a report identifying a column as a prompt, and controlling how the report author sees the prompt information Because reports can contain different query items from one or more objects in the model, query item properties control many aspects of the final report. When you create a model dimension or model query subject, the query items inherit the properties of the data source query items on which they are based. The properties for query items or measures include the following. Query item property Name Description Last Changed Screen Tip Expression Description The name of the query item or measure. A description of the query item or measure. The date that the query item or measure was last changed. A description that can appear in the published package for the report authors. Used to create embedded calculations that provide report authors with calculated values that they regularly use. This property is for measures only. External Name The name that appears in the data source.

User Guide 111

Chapter 4: Preparing Relational Metadata for Use in Reports

Query item property Is Hidden

Description Whether to hide or show the query item or measure in the published package. Even when Is Hidden is set to True and the query item or measure is invisible to report authors, it is always present in the published package because the query item or measure may be needed by other objects in the model. You do not see the query item or measure in the Package Publish wizard. For example, a calculation may make use of a hidden query item.

Usage

The intended use for the data represented by the query item. This property is for query items only.

Format Currency

How information appears in a report. Which currency is used. This property cannot be changed in the Property pane. Use the Format property to change the currency.

Data Type

The data type that was set in the data source. Because this property is set in the data source, it is read-only in Framework Manager.

Precision

The number of decimal places. Because this property is set in the data source, it is read-only in Framework Manager.

Scale

How many digits are represented in the scale. For example, you can show numbers in thousands so that 100,000 means 100,000,000. Because this property is set in the data source, it is read-only in Framework Manager.

Size

The size of the query item or measure. Because this property is set in the data source, it is read-only in Framework Manager.

Is Nullable

Whether the query item or measure can contain a null value. Because this property is set in the data source, it is read-only in Framework Manager.

Display Type

How the query item is shown. The column value can appear in the reporting application as a picture, as a link, or as a value. The default is value. This property is for query items only.

112

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Query item property MIME Type

Description The format that the column value uses. For example, if Display Type is set to picture, MIME Type could be jpeg. This property is for query items only. Note: The MIME Type property is not used by SAP BW.

Prompt Info Regular Aggregate Semi-Aggregate

Prompt behavior. The type of aggregation that is associated with the query item, measure, or calculation in the published package. The value that is set in the data source. For relational metadata, the Semi-Aggregate property value is set to unsupported, and the property is read-only. For SAP BW metadata, the Semi-Aggregate property shows the value that is set in the data source, and the property is read-only.

Is Unsortable

Whether the values of this query item can be sorted. This property is for query items that contain large objects such as BLOBs.

You can rename a query item in the Calculation Definition dialog box. Renaming the query item updates references to this query item. For information about the Usage, Regular Aggregate, and Semi-Aggregate properties, see (p. 113) formatting the query item, see (p. 117) prompts, see (p. 118)

Modifying How Query Items Are Aggregated

For information about aggregation of SAP BW query items, see (p. 166). You can change how some query items and measures are aggregated in reports. Framework Manager applies aggregation rules when report authors create a report that uses an aggregated query item or measure. When you import metadata, Framework Manager assigns values to the Usage, Regular Aggregate, and Semi-Aggregate properties for query items and measures depending on the type of object that the query item or measure is in. The Usage property sets the aggregation rules and also drives transformations, such as star schemas. The Regular Aggregate and Semi-Aggregate properties identify the type of aggregation that is associated with the query item or measure. Report authors can override the values you set. The types of objects that query items or measures can be in are dimensions query subjects calculations You can change existing Usage and Regular Aggregate property values by either automatically regenerating the values of selected objects You then know that these values are appropriate for the type of data they represent. modifying the values in the Properties pane

User Guide 113

Chapter 4: Preparing Relational Metadata for Use in Reports You can select additional aggregation values that are not available through importing, such as average and maximum. You must understand what the data represents to know which aggregation rule is required. For example, if you aggregate a part number, the only aggregate values that apply are count, count distinct, count non-zero, maximum, and minimum.

Rules for Setting Properties for Dimensions

Framework Manager uses the following rules to set the Usage, Regular Aggregate, and Semi-Aggregate properties. Object Regular dimension Usage property Attribute Regular Aggregate property Unsupported Automatic if it is a calculation Sum if it is not a calculation Count Unsupported Semi-Aggregate property Unsupported Unsupported

Measure in a measure Fact dimension Query item in a measure dimension Identifier

For multidimensional metadata, you cannot change these properties for data source dimensions.

Rules for Setting Properties for Query Subjects

You can change the Usage, Regular Aggregate, and Semi-Aggregate properties for all types of query subjects. The settings for these properties are based on characteristics such as data type and participation in keys and relationships. For model query subjects, Framework Manager uses the settings for the query subject that the model query subject is based on. If the source query subject does not use these properties, the rules for data source and stored procedure query subjects are applied. For data source or stored procedure query subjects, Framework Manager uses the following rules to set the Usage, Regular Aggregate, and Semi-Aggregate properties when importing the query subjects. Query Item Is part of a key in a determinant, participates in a relationship, or is the data type date or time Usage property Identifier Regular Aggregate property Count Semi-Aggregate property Unsupported

Is the data type numeric or Fact time interval

Automatic if it is a calculation Sum if it is not a calculation Unsupported

Automatic if it is a calculation Sum if it is not a calculation

None of the above apply

Attribute

Unsupported

Rules for Setting Properties for Calculations

Framework Manager uses a number of rules for setting the Usage and Regular Aggregate properties for calculations.

Rules for Interpreting Calculated Aggregations

The calculated aggregation type is used only for stand-alone calculations. For stand-alone calculations, Framework Manager uses the following rules to interpret the Regular Aggregate property: Standard aggregation functions (average, count, maximum, minimum, standard deviation, sum, variance) and references to model query subjects are aggregated first. The remaining operations are then applied to the aggregation result. For example, to divide debt by credit for each row, the SQL looks like this: 114 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Select customer, debt, credit, debt/credit as percent_debt from x

To aggregate for all customers, the SQL looks like this:

Select sum(debt), sum(credit), sum(debt)/sum(credit) from (Select customer, debt as percent_debt from x)

If the query item in the calculation is a fact and the aggregation type for the query item is average, count, maximum, minimum, or sum, the aggregation type of the query item is used. If the query item in the calculation has no aggregation type set, the minimum type is applied in the query. It is not possible in SQL to have an aggregation setting of none. Aggregate functions are interpreted as if they are applied to a value in a single row when these functions are used in the detail context. For example, a Report Studio report has the Auto Group and Summarize property set to false. Aggregation of a query item is based on the aggregated expression derived from the item definition. For example, you want to total this stand-alone calculation:
[namespace].[Company].[debt] / [namespace].[Company].[credit]

The calculation is aggregated with this expression:

Total([namespace].[Company].[debt]) / Total([namespace].[Company].[credit])

Scalar aggregates, also known as running, ranking, and moving aggregates, are calculated for report granularity unless the For clause is explicitly specified. Granularity of aggregate functions is set by grouping for determinants or by keys of corresponding levels in the cube. For example, Rank([namespace].[Company].[debt] is interpreted as Rank([namespace].[Company].[debt] for Report).

Rules to Determine the Automatic Aggregation Type

For stand-alone and embedded calculations, Framework Manager uses one of these rules to determine the aggregation type. Calculation Is based on an expression containing an aggregate function such as average, maximum, minimum, or sum Has an if-then-else operation and the if condition references fact items
References a calculation using any type except unsupported

Aggregation type Calculated Calculated Calculated Calculated Summarize See below for the rules for summarize. Unsupported

Has an aggregation type other than unsupported Is based on an expression that references a model query subject whose usage is set to fact and whose aggregation type is set to average, count, maximum, minimum, or sum but the query item expression does not use an aggregate function None of these rules apply

Rules to Determine the Summarize Aggregation Type

For stand-alone and embedded calculations, Framework Manager uses one of these rules to determine the aggregation type. Calculation Is a fact containing of only a reference to a query item whose aggregation type is average, count, maximum, minimum, or sum Numeric or an interval type Aggregation type Uses the aggregation type of the query item Sum User Guide 115

Chapter 4: Preparing Relational Metadata for Use in Reports

Calculation Time, datetime, or date type None of these rules apply

Aggregation type Maximum Count

Usage Property
The Usage property identifies the intended use for the data represented by each query item. During importing, the Usage property is set according to the type of data that the query items represent in the data source. You need to verify that this property is set correctly. For example, if you import a numeric column that participates in a relationship, the Usage property is set to identifier. You can change the property. For relational query items, the value of the Usage property depends on the type of database object the query item is based on. Usage property Identifier Database object key, index, date, datetime Description Represents a column that is used to group or summarize the data in a Fact column with which it has a relationship. Also represents an indexed column. Also represents a column that is of the date or time type. Fact numeric, timeinterval Represents a column that contains numeric data that can be grouped or summarized, such as Product Cost. string Represents a column that is neither an Identifier or Fact, such as Description.

Attribute

Regular Aggregate Property

The Regular Aggregate property identifies the type of aggregation for the query item or calculation when you publish it. The report author can either use this default setting to perform calculations on groups of data, or apply a different type of aggregation. For example, if the Regular Aggregate property value of the Quantity query item is sum, and the report author groups it by Product Name, the Quantity column in the report shows the total quantity of each product. The following aggregation types are supported for relational data sources: automatic average calculated count count distinct maximum minimum sum

Semi-Aggregate Property
For relational metadata, the Semi-Aggregate property value is set to unsupported and is read-only. If the value is set to unsupported in Framework Manager, the semi-aggregate behavior is ignored in the report authoring tools.

116

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Regenerate Usage and Aggregation Property Values

For information about regenerating values for SAP BW query items, see (p. 169). Using Framework Manager to regenerate the values of the Usage and Regular Aggregate properties ensures that they reflect the transformation rules. It is useful to regenerate these values before you publish a package to ensure that these properties reflect modifications to your model. When generating aggregation values, Framework Manager assigns a value that is based on the Usage property value, and the type of model object it is. Usage property value Identifier Attribute Fact Regular Aggregate property value Count Unsupported Sum

Steps
1. 2. 3. 4. 5. 6. In the Project Viewer pane, click one or more dimensions or query subjects. In the Properties pane, click the Properties tab. Change the Usage property to unknown. Change the Regular Aggregate property to unsupported. From the Actions menu, click Determine Usage. From the Actions menu, click Determine Aggregation Rules.

Format Query Items

For information about formatting query items based on SAP BW metadata, see (p. 169). You can specify how query item values appear in a report. Use the Format property to choose a format type, such as text, date, and currency. Each format type contains properties that further specify how the data appears. For example, you can assign the Currency format type to a numeric query item, and then use the No. of Decimal Places property in the Data Format dialog box to specify how many decimal places appear in reports. Some characters are language-sensitive and appear properly only when your locale supports the applicable font. For example, for Japanese currency symbols to appear correctly, your locale must be set to Japanese. You can define properties for several query items at the same time. However, if the query items have different format types, all properties that were previously specified are overridden and the default values from the data source are used. If the original format types of the selected query items are the same, all the properties for the selected query items are set identically. For example, to use the same decimal separator for two query items and to keep the number of decimals different, each query item must be changed individually. If both are selected and changed at the same time, all properties including the number of decimals are set identically for both query items.

Steps
1. 2. 3. 4. 5. In the Project Viewer pane, click the query item you want to format. In the Properties tab of the Properties pane, click the Format property. Select the appropriate Format type. In the Properties box, select or type the appropriate property value. Click OK.

User Guide 117

Chapter 4: Preparing Relational Metadata for Use in Reports

Define a Prompt Control

For information about prompt controls for SAP BW metadata, see (p. 170). Prompts help users quickly find the information they need in a report. Prompts are generally defined in reports. However, you can change the definition of the dimension or query subject in the model so that a prompt appears automatically when report authors create filters. This is useful for query items, such as ProductTypeCode, whose values are not shown in a report but are useful for filtering data. In Framework Manager, prompt behavior is defined through a compound query item property named Prompt Info. The Prompt Info property contains the properties that affect how prompt controls are generated by Cognos 8.

Prompt Types
The Prompt Type property sets the type of prompt control that is generated when the report is run, such as an edit box or a pull-down list. Use this property to have the prompt show one query item but use a different one. For example, the prompt can show Employee Name but use Employee Number. The default value for this property is Server Determined. Value Prompt Control

Server Determined The type of prompt control is based on information in the server, such as the data type of the query item. Edit Box A simple text box. If the data type of the column is date or dateTime, this value generates a date or date-time control as well as the text box. A date control with a calendar interface. A date-time control with a calendar interface. For SAP BW metadata, this value is not relevant. A date-time interval control. For SAP BW metadata, this value is not relevant. A time control that filters data based on the selected time period. For example, if you define a Select Time prompt for Order Time, the user can use the time control to show all orders placed after 1:00, or all the orders placed between 10:00 and 11:00. If you are referring to a time member, you must use the exact values only. If you are using a range, the end points of the range must correspond to values in the data source. Select Value A drop-down list.

Select Date Select Date/Time Select Interval Select Time

Select with Search A list control so that users can search for values. For SAP BW metadata, this value is not relevant. Select with Tree A tree prompt control for prompts that are based on a hierarchy node.

Parent Item in a Cascading Prompt

The Cascade on Item Reference property indicates that the generated prompt is part of a series of generated cascading prompts. The query item that you reference in this property is the parent item in the cascade. The system prompts the user for the cascade item before prompting them for the current query item.

118

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports For example, if you want to prompt for Product Line and then Product within the selected line, set the Cascade On Item Reference property of the Product query item to Product Line.

Display Item to Show

The Display Item Reference property identifies the query item that the prompt shows if it is different from the query item whose properties you are editing. For example, if you want to prompt the user for Product Number but show the Product Name to the user, set the Display On Reference property of the Product Number query item to Product Name. This property is used only for data driven prompt controls whose Prompt Type properties are set to either Select Value or Select with Search.

Alternative Query Item for Filters

The Filter Item Reference property identifies an alternative query item that is used by any Report Studio or Query Studio filter. This property is used only when Report Studio or Query Studio generates a filter. This property helps create more efficient queries, because it is faster to filter on an indexed numeric column than a non-indexed string column. For example, if a report author wants to create a Product Name filter that uses the values in Product Number, you can set the Filter Item Reference property of Product Name to Product Number. You can also set the Display Item Reference property of the Product Number query item to Product Name, so that the user is prompted to select a name rather than a product number.

Steps
1. 2. 3. 4. Click the query item. In the Properties pane, click the Properties tab. Click the plus sign (+) next to the Prompt Info property. Modify the prompt properties to reflect the behavior you require.

Convert a Query Item into a Measure

You can convert a query item in a measure dimension back into being a measure. You can also convert a measure to a query item (p. 85).

Steps
1. 2. 3. 4. Double-click the measure dimension that contains the query item. Click the Measure Dimension tab. Right-click the query item and click Convert to Measure. Click OK.

Modify Multiple Objects at Once

For information about modifying SAP BW objects, see (p. 171). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order. 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show.

User Guide 119

Chapter 4: Preparing Relational Metadata for Use in Reports 4. Make any changes to the values of the property.

Adding Business Rules

For information about business rules for SAP BW metadata, see (p. 171). You can add business rules to the dimensions and query subjects in your model to refine the data retrieved and ensure that the right information is available for report authors. You can add calculations so that report authors can include calculated data in their reports (p. 120) create and apply filters so that you can limit the data that a query subject retrieves (p. 122) add prompts so that users are prompted to filter data when they open a report (p. 125) use session parameters (p. 128) and parameter maps (p. 125) in macros (p. 129) to dynamically resolve expressions

Advantages
Creating business rules and storing them in the model instead of in reports has these advantages: They save time. You and your users do not have to re-create them every time they are needed. They ensure consistency. Your users all use the same definitions. For example, Low Margin means the same thing throughout the organization. They are easy to update. You can maintain the business rules centrally so that all reports are updated automatically as the rules evolve. For example, if the definition for Low Margin changes, all reports that use the Low Margin calculation are updated automatically. They enhance security. For example, you can use filters to limit the data that your users can see.

Create a Calculation
For information about calculations for SAP BW metadata, see (p. 172). You can create calculations to provide report authors with calculated values that they regularly use. Calculations can use query items, parameters, variables, calculated members, expressions, and expression components, such as functions. Punctuation characters, such as the question mark (?), must be in 7-bit ASCII character code. If you type a punctuation character from a multi-byte enabled keyboard, ensure that you type the 7-bit ASCII representation of the character. For example, type Alt+063 for the question mark. Avoid using characters that are used for expression operators in the name of the calculation. Syntax errors may occur when the expression is evaluated. For example, a calculation named Margin * 10 causes errors when used in an expression such as [Margin * 10]< 20. At query time, Framework Manager returns a null value for any calculation that contains a divisor whose value is zero. Framework Manager cannot detect zero-division errors in functions such as average and mod, because the division operator is not explicit. Framework Manager supports two types of calculations: stand-alone and embedded.

Stand-alone Calculations
Use a stand-alone calculation when you want to reuse the expression. You can apply a stand-alone calculation to one or more dimensions or query subjects to provide calculated data to a report, or include it in a package to make it available to your users. By moving a stand-alone calculation or a shortcut to it into a folder, you can better organize your model objects. 120 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Embedded Calculations
You may want to use a calculation with only one dimension or query subject. You can create an embedded calculation when modifying a relational data source query subject, model query subject, or dimension. If you start with an embedded calculation, you can later convert it into a stand-alone expression that you can apply to other dimensions or query subjects. Tip: Right-click the calculation expression in the Calculations tab and click Convert to Stand-Alone Calculation.

Steps
1. Do one of the following: If you want to create a stand-alone calculation, click the model folder and, from the Actions menu, click Create, Calculation. If you want to create an embedded calculation, double-click the dimension or query subject that will contain the calculation, click the Calculations tab, and then click Add. 2. In the Name box, type a name for the calculation. 3. Define the expression. Goal Add items Add functions Add parameters Action On the Model tab, click a query item, filter, or calculation and click the arrow. On the Functions tab, choose a component and click the arrow. On the Parameters tab, click a parameter and click the arrow.

Limit test results Click the options button, select the Restrict the maximum number of rows to be returned check box, and type the required number of rows to be returned. Override session Click the options button, click Set, enter a value in the Override parameters Value field, and click OK.

Override prompt Click the options button, and then click Prompts. values The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model.

4. To test the calculation, click the test button. You can test only calculations that contain query items. If a calculation contains a function, for example _add_days, the test sample button is not available. 5. Click OK. 6. Modify the Data Type property to identify the type of data the calculation returns. The report authoring tool uses this information to format the data that the calculation returns.

Notes for Embedded Calculations

When you embed a calculation, the data source query subject must have a relationship to any query subject referenced by the expression. This relationship is necessary even if the expression references a model query subject based on the same table as the data source query subject in which you are embedding the expression. To create a calculation on an unrelated query subject, do one of the following:

User Guide 121

Chapter 4: Preparing Relational Metadata for Use in Reports Ensure that there is a join path between the new query subject and the one that contains the calculation. Base the embedded calculation on a query item that is based on the data source query subject you want. Convert the calculation to a stand-alone calculation, so that it is not part of the query subject. Create a stand-alone calculation that references the embedded object.

For information about functions, see "Using the Expression Editor" (p. 259) overriding session parameters, see "Create a Session Parameter" (p. 128) testing, see "Test a Query Subject, Query Set, or Dimension" (p. 98) or "Test a Dimension, Query Subject, or Query Set" (p. 86)

Create a Filter
For information about filters for SAP BW metadata, see (p. 174). A filter is an expression that specifies the conditions that rows or instances must meet to be retrieved for the dimension, query subject, calculation, or report to which the filter is applied. A filter returns a boolean value so that you can limit the rows returned by a dimension or query subject. For example, you can use the in_range function to create a filter that retrieves data for products introduced in a specific time frame. The syntax for this example looks like this:
[gosales_goretailers].[Products].[Introduction date] in_range {Feb 14, 1999 : July 14, 2005}

Note: When using a date or time function, you must use a 24-hour clock. Framework Manager does not support "a.m." or "p.m." in expressions. For example, use 20:00 to signify 8 p.m. You can restrict the data represented by dimensions or query subjects in a project by creating a security filter. The security filter controls the data that your users can see when they set up their reports. You can also apply governors to restrict the data that the queries in a package retrieve. Framework Manager supports two types of filters: stand-alone and embedded.

Stand-alone Filters
Use a stand-alone filter when you want to reuse the expression. You can add a stand-alone filter to one or more dimensions or query subjects to limit the data that the query retrieves when the filtered dimension or query subject is used in a report, or you can include it in a package to make it available to your users. By moving a stand-alone filter or a shortcut to it into a folder, you can better organize your model objects.

Embedded Filters
You may want to use a filter with only one dimension or query subject. You can create an embedded filter when modifying a dimension, relational data source query subject, or model query subject. If you start with an embedded filter, you can later convert it into a stand-alone expression that you can apply to other dimensions or query subjects. Tip: Right-click the filter expression in the Filters tab and click Convert to Stand-alone Filter.

Steps
1. Do one of the following: If you want to create a stand-alone filter, click the model folder and, from the Actions menu, click Create, Filter. If you want to create an embedded filter, double-click the dimension or query subject that will contain the filter, click the Filters tab, and then click Add. 2. In the Name box, type a name for the filter.

122

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 3. Define the expression. Goal Action

Add query items On the Model tab, drag the objects you want to the Expression and filters Definition box. Add functions On the Functions tab, drag the functions to the Expression Definition box.

Add parameters On the Parameters tab, drag the parameters to the Expression Definition box. Limit test results Click the options button, select the Restrict the maximum number of rows to be returned check box, and type the required number of rows to be returned. Override session Click the options button, click Set, enter a value in the Override Value parameters field, and click OK.

Override prompt values

Click the options button, and then click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model.

4. To test the filter, click the test button. 5. Click OK.

Notes for Embedded Filters

When you embed a filter, the data source query subject must have a relationship to any query subject referenced by the expression. This relationship is necessary even if the expression references a model query subject based on the same table as the data source query subject in which you are embedding the expression. To create a filter on an unrelated query subject, do one of the following: Ensure that there is a join path between the new query subject and the one that contains the filter. Base the embedded filter on a query item that is based on the data source query subject you want. Convert the calculation to a stand-alone filter, so that it is not part of the query subject. Create a stand-alone filter that references the embedded object. You can also apply governors to restrict the data that the queries in a package retrieve (p. 194). For information about security filters, see (p. 200) functions, see "Using the Expression Editor" (p. 259) parameters, see (p. 125) session parameters, see (p. 128) testing, see "Test a Query Subject, Query Set, or Dimension" (p. 98) or "Test a Dimension, Query Subject, or Query Set" (p. 86)

Applying a Filter
For information about filters for SAP BW metadata, see (p. 175).

User Guide 123

Chapter 4: Preparing Relational Metadata for Use in Reports To apply a filter, you must modify the dimension, data source query subject, or model query subject. The query subject must either contain the query items that the filter references, or have a relationship path to the query subjects that contain the query items. You can embed a stand-alone filter in dimensions or query subjects, but if you want a different usage for each embedded filter, you must create different versions of the stand-alone filter. Otherwise, your users could be required to fill in a prompt that you thought was optional if there is any instance where the usage is set to mandatory. For example, in query subject A, you define the embedded filter as optional. In query subject B, you define it as mandatory. When your users create a report that uses both query subjects, they are required to choose values in both filters, even the one defined as optional. All instances of the filter are considered to be mandatory when used in the same query. The solution is to create different versions of the filter, each with its own name. When you apply a filter, you specify how it is used by selecting one of the following usage values. Always Applies the filter whenever the dimension or query subject is run, regardless of whether the report contains the query item that is filtered. Always is the default usage value. Use this usage value to ensure specified data is filtered out of all reports. For example, your company may have obsolete information that it stores but does not want to report on. Design Mode Only Limits the amount of data that the report authors and modelers retrieve when designing. By limiting data retrieval, design-time results appear much more quickly. Optional Does not need to be applied. The user is prompted to filter data and can leave the filter blank. The report retrieves all data for the dimension or query subject. Applies only to filters that use the ? ? syntax.

Example - Create and Apply a Filter to Relational Metadata

You want to create a query that shows the currency name for a specific country. To do this, you create a filter that returns data for a specific country code, and apply the filter to a model query subject that retrieves the currency name for each country. Note: The following example uses a relational data source.

Steps
1. Open the gosales_goretailers sample model. It is located in c8_location/webcontent/samples/Models/gosales_goretailers/gosales_goretailers.cpf 2. Create a filter to limit the retrieval of data to only those country codes in the conversion rate table whose value is 2: Click the Filters folder and, from the Actions menu, click Create, Filter, and name the new filter ConversionRateCountryCode. Click the Model tab. In the Available Components box, open the Database view folder and then open the GoSales folder. Add the Country Code query item from Conversion Rate query subject to the Expression definition box, and type ='2' at the end of the expression. Click OK. 3. Create a model query subject named ISO Code. In the Available Model Objects box, open the Database view folder. Add Country query item and the ISO 3-letter code query item from the Country query subject to the Query Items and Calculations box. 4. Apply the ConversionRateCountryCode filter: Click the Filters tab. Open the Filters folder and drag ConversionRateCountryCode to the Filters box. 124 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 5. Click the Query Information tab. The generated SQL contains the filter even though it does not affect the result set. 6. Change the usage of the ConversionRateCountryCode filter to Optional: Click the Filters tab. Right-click Usage for the ConversionRateCountryCode filter, and click Change Usage, Optional. The default usage is Always. 7. Click the Query Information tab to view the SQL. 8. Click OK.

Using Prompt Values to Filter Data

For information about prompt values for SAP BW metadata, see (p. 176). You can substitute a prompt for a value so that users can filter data by typing a value when the report opens. In general, it is better to define type-in prompts in the reports to make use of the additional prompt features. However, report authors cannot modify some variables. For these variables, you can use Framework Manager to define type-in prompts. You can use prompts in parameter maps session parameters stored procedure arguments expressions, including filters, calculations, and relationships The syntax for using a prompt as a value is
?<PromptName>?

For example, a stored procedure returns all rows with a specific product number. Instead of using the product number as the argument for the stored procedure, you can use a prompt, such as ?Product_Number?. When you test a model object that references a prompt, Framework Manager asks you to enter the prompt value. Framework Manager uses this value for either the duration of the session, or until you clear the prompt value. You can change the session value of prompt values through the Options dialog box. This dialog box is available when you modify a dimension or query subject, or define a calculation, filter, query set, or complex relationship. You can change the prompt value at the time that you are testing the expression that references that value. If you select the Always prompt for values when testing check box in the Prompt dialog box, Framework Manager prompts you for a value every time you test the object. When updating the object or performing a count, Framework Manager uses the existing prompt value, if one exists. You can also set up prompt properties for query items. For more information, see "Define a Prompt Control" (p. 118).

Create a Parameter Map

For information about parameter maps for SAP BW metadata, see (p. 183). Use parameters to create conditional query subjects that allow for substitutions when the report is run. Parameter maps are objects that store key-value pairs. Parameter maps are similar to data source look-up tables. Each parameter map has two columns, one for the key and one for the value that the key represents. You can manually enter the keys and values, import them from a file, or base them on existing query items in the model. All parameter map keys must be unique so that Framework Manager can consistently retrieve the correct value. Do not place quotation marks around a parameter value. You can use quotation marks in the expression in which you use the parameter.

User Guide 125

Chapter 4: Preparing Relational Metadata for Use in Reports The value of a parameter can be another parameter. However, you must enclose the entire value in number signs (#). The limit when nesting parameters as values is five levels. When you use a parameter map as an argument to a function, you must use a percentage sign (%) instead of a dollar sign ($).

Parameter Map Based on a Query Item with a Large Result Set

We recommend that you do not use a query item or table that contains many rows, such as 50,000 rows. Each time you use the parameter map in an expression or in SQL, Framework Manager executes this large query. Performance is then slowed. Parameter maps are recommended for smaller lookup tables.

Steps to Manually Create a Parameter Map

1. 2. 3. 4. Click the Parameter Maps folder and, from the Actions menu, click Create, Parameter Map. In the Name box, type a name for the new parameter map. Click Manually enter the parameter keys, and/or import them from a file and click Next. Choose how to enter values: To manually enter values, click New Key, type a key, and press Tab to enter a value for that key. To import keys and values, click Import File and identify the location of the appropriate .csv file. You can import from a .txt file only if the values are separated by tabs rather than commas. Note: If you are going to use a parameter in a data source query subject, the value must use English-specific punctuation. This means that you must use a period (.) to represent a decimal and a comma (,) to separate lists of values. 5. Modify existing parameters as required. Goal Assign a default value Action In the Default Value box, type a value. If the key is used in an expression that is not mapped, the default value is used. Select a row and click Delete. Select the row you want to modify, click the Edit button, and type a value. Click Clear Map.

Remove a parameter Modify a parameter Clear all keys and values 6. Click Finish.

Steps to Create a Parameter Map Based on Existing Query Items

1. 2. 3. 4. Click the Parameter Maps folder and, from the Actions menu, click Create, Parameter Map. In the Name box, type a name for the new parameter map. Click Base the parameter map on existing Query Items and click Next. Click the query item to use as the key, and then click the query item to use as the value. Both query items must be from the same query subject. 5. Click Next. You can assign a default value. If the key used in an expression is not mapped, the default value is used. 6. Click Finish. For information about using parameters, see "Creating Prompts with Query Macros" (p. 129)

126

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports parameterized XML connection strings, see (p. 63) examples of parameter maps, see "Example - Specifying a Language Value for Relational Metadata" (p. 127) and "Example - Moving a Relational Model from One Environment to Another" (p. 127)

Example - Specifying a Language Value for Relational Metadata

An international company stores its product information in English and French. With the use of a parameter map and macros, employees can retrieve data that matches the information they require.

Language_lookup Parameter Map

Key en fr

Value EN FR

When you examine the SQL for the Product Line query subject, you see the following:
Select PRODUCT_LINE.PRODUCT_LINE_CODE, #'PRODUCT_LINE.PRODUCT_LINE_' + $Language_lookup{$runLocale}# as Product_Line from [gosales].PRODUCT_LINE PRODUCT_LINE

The runLocale macro returns a locale setting that is used by the Language_lookup macro to specify a language value.

Example - Moving a Relational Model from One Environment to Another

You want to move a model from a test environment to a production environment. This example is based on the GO Sales data warehouse, which accesses Microsoft SQL Server. You can change the data source of a model from one relational vendor to another relational vendor. It does not matter if the data is dimensionally modeled. You cannot change the data source of a model from a relational vendor to an OLAP data source. You cannot change the data source of a model from one OLAP data source to another OLAP data source.

Steps
1. Create two parameter maps, one for the Catalog property and one for the Schema property of the data source. These parameter maps are used in macros to set the properties of the data source at run-time. Here is the Datasource_Catalog parameter map. Key TEST_USER PRODUCTION_USER Value GOSLDW_TEST GOSLDW_PRODUCTION

Here is the Datasource_Schema parameter map. Key _MSSQL_TEST Value dbo

User Guide 127

Chapter 4: Preparing Relational Metadata for Use in Reports

Key _MSSQL_ODBC_PRODUCTION

Value dbo

2. In the Catalog property for the data source, insert a macro that uses a value in the Datasource_Catalog parameter map based on the account.defaultName session parameter. The syntax looks like this:
#$Datasource_Catalog {$account.defaultName}#

3. In the Schema property for the data source, insert a macro that uses a value in the Datasource_Schema parameter map. The syntax looks like this:
#$Datasource_Schema {$account.defaultName}#

Create a Session Parameter

For information about session parameters for SAP BW metadata, see (p. 184). A session parameter is a variable that Framework Manager associates with a session. For example, user ID and preferred language are both session parameters. Because session parameters are key and value pairs, you can think of each session parameter as an entry in a parameter map named Session Parameters. You use a session parameter in the same way that you use a parameter map entry, although the syntax for session parameters is slightly different. You can define additional parameters by using model session parameters. Each session parameter must have a name and a default value. You can define an override value to test the results that value returns. The override value is valid only when you have the model open, and is not saved when you save the model. If no override value exists, Framework Manager uses the default value when it executes a query that contains a session parameter. The rules governing the use of parameters include the following: All possible return values must have the same data type. Only one value can be defined. There are two types of session parameters: environment and model.

Environment Session Parameters

Environment session parameters are predefined and stored in Content Manager. By default, the following session parameters appear in Framework Manager: runLocale account.defaultName account.personalInfo.userName If you log on anonymously, you will see only runLocale and account.defaultName(Anonymous). If your authentication source supports other parameters and you entered information about them in the authentication source, you see other session parameters, such as account.personalInfo.email.

Model Session Parameters

If you need a session parameter that does not exist, you can create a model session parameter. Model session parameters are stored in a parameter map named _env. They are set in the project and can be published with a package. Model session parameters must have their values set within the scope of objects in the Framework Manager model. The scope can include the use of existing environment session parameters, as well as static values.

Steps
1. From the Project menu, click Session Parameters. 2. Click New Key and type a session parameter key and value. 128 Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports 3. Choose how to handle the override value. To avoid having to set the override value every time you edit the project, set the session parameter as a value. To avoid having to remove the project setting each time before you publish it, set the session parameter as a session override. 4. Modify existing parameters as required. Goal Change the parameter value Assign a default value Remove a parameter Clear an override value 5. Click Finish. Action Click the row that contains the value you want to change, click Edit, and type a value. In the Default Value box, type a value. Framework Manager uses the default value if a key has an invalid value. Click a row and click the Delete button. You cannot delete an environment session parameter. Click a row and click Clear Override.

Using Parameters with Relational Data Source Query Subjects

Model objects do not reflect changes to the data source objects on which they are based. Therefore, when you add a parameter to a data source query subject, consider whether you want to create a model object that references the parameter. If so, you must assign an alias to the parameterized object in the data source query subject. This ensures that any model query subjects, filters, or calculations that reference the object return the correct results when the parameter value changes. For example, the following SQL defines a data source query subject that contains a session parameter named runLocale. The runLocale parameter value specifies which column the query retrieves. The alias behaves like a shortcut so that when a model object references CountryNameAlias, Framework Manager retrieves the value to which the alias is assigned.
Select #$ColumnMap{$runLocale}# as CountryNameAlias From [GoSales].Country

Creating Prompts with Query Macros

Macros are fragments of code that you can insert anywhere in the Select statement that defines a query subject. You can include references to session parameters, parameter maps, and parameter map entries. Parameter values are set when you run the query. For example, you can use the language session parameter to show only the data that matches the language setting for the current user. Macros can be used in these different ways: They can be inserted in the SQL. An example is Select * from Country where Country.Name = #$myMap{$runLocale}# They can supply an argument to a stored procedure query subject. If a value is not hard-coded for the argument, the stored procedure query subject can be used to return different data. They can be inserted in expressions, such as calculations and filters. An example is a filter [gosales].[Sales staff].[Staff name] =
#$UserLookUpMap{$UserId}#

User Guide 129

Chapter 4: Preparing Relational Metadata for Use in Reports They can be used to dynamically complete the properties of a data source query subject. This enables different users to supply different connection information and thus access different data sources. The properties that can contain macros are: Content Manager Datasource, Catalog, Cube, and Schema. An example using the Content Manager Datasource property is
#$DataSourceMap{$UserId}#

They can be used as a parameter wizard. Parameters can reference other parameters. An example is Map1, Key = en-us, Value =
#$myMap{$UserId}#

They can be used in the Session Parameter dialog box. An example is MySessionParameter, value = #$myMap{$UserGroup}#

Do not insert macros between existing quotation marks or square brackets because Framework Manager does not execute anything within these elements. You can replace the following query subject elements with a parameter. Element Query items identified in the Select list Tables identified in the From clause
Where clause

Example
#'Product_name_'+ $languageCode# Product_#$language# Product_lang = #sq($languageCode)# #$data_source#.#$schema#.Products

Name of the data source, schema, or source property

Syntax
Use the following syntax to reference session parameter and parameter values. Object Session key Parameter map key Syntax
$session_key $map{<key>}

Example
#$my_account# #$map_one{'abc'}#

Parameter map entry whose key is $map{$session_key} #$map_one{$my_account}# defined by a session parameter When you reference a parameter, you must use a number sign (#) at the beginning and end of each set of one or more parameters. Everything between the number signs is treated as a macro expression, which is processed at runtime. Framework Manager removes anything that is outside the number signs when running the macro. precede each parameter map entry with a dollar sign ($) use a name that starts with an alpha character (a..z, A..Z)

130

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports You can add the following elements to further define the macro expression. Symbol Single quotation marks Purpose Delineates a literal string that has a single quotation mark as part of the string. If the single quotation mark appears in a string, such as a query item, the string must be enclosed in a single quotation mark on both sides of the string and the single quotation mark must be doubled. For example, ab'c is written as 'ab''c' If the single quotation mark appears in a macro, the string must be enclosed in square brackets. For example, ab'c is written as [ab'c] If the single quotation mark appears in a prompt, there is no need to enclose the string. To escape a single quotation mark in an expression, use &apos; Square brackets Encloses model objects, such as a namespace or query subject and macro names that contain restricted characters, such as a number sign, hyphen, or space. Calls a function that is unknown to the parser, such as dateadd in DB2, and whose first argument is a keyword. Example:
dateadd ({month},2,<date expression>)

Curly brackets

+ operator

Concatenates two strings, such as 'abc' + 'xyz'

Single quote function Surrounds the result of a string expression with single quotation marks. Existing single quotation marks are double-escaped so that they do not (sq) interfere with the quotation structure. You can use this function to build clauses to test against literal parameter-driven values. Here is an example:
#sq($my_sp)#

If a session parameter (my_sp) has the value ab'cc, the result is

'ab"cc'

Double quote function (dq)

Surrounds the result of a string expression with double quotation marks. You can use this function to refer to table and column names with non-identifier characters, such as a blank space or a percent sign (%). Here is an example:
#dq ('Column' + $runLocale)#

If runLocale=en-us, the result is

"Column en-us"

Square bracket function (sb)

Inserts a set of square brackets into the argument to build object references in a model query and model expressions, such as filters and calculations. Here is an example:
#sb ('my item in ' + $runLocale)#

If runLocale=en-us, the result is

[my item in en-us]

For information about functions, see "Using the Expression Editor" (p. 259).

Steps
1. Select the data source query subject you want to modify. User Guide 131

Chapter 4: Preparing Relational Metadata for Use in Reports 2. From the Actions menu, click Edit Definition. 3. On the SQL tab, click Insert Macro to start the Macro Editor. 4. In the Available components box, click the parameter maps, session parameters, or functions you want to use, and drag them to the Macro definition box. 5. Insert single or double quotation mark functions. Tip: Click the arrow next to these buttons for a menu of choices for placing the quotation marks. 6. If you want to edit a parameter map or session parameter, in the Macro definition box, click it. The Parameter Map or Session Parameters dialog box appears. You can set override values for session parameters, add new items, or change values. 7. Check the macro in the Information box. If a macro is incorrect, an error message appears. Tip: To clear a macro, click the clear all button. 8. Click OK.

Mandatory and Optional Prompts

You can create mandatory and optional prompts in Framework Manager models by using query macros. You can use two prompt macro functions, prompt and promptmany, to create single value and multiple value prompts. You can insert a prompt macro anywhere in the SQL statement that defines the query subject. If you want to use a prompt macro in an expression such as a calculation, you must specify the data type when using an overloaded operator, such as a plus sign (+). You can use the plus sign to concatenate two items and to add two items. Here is an example of a mandatory prompt:
select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY = #prompt('CountryName')#

The prompt and promptmany functions have the following parameters. All argument values must be specified as strings. Parameter Name (mandatory) Datatype (optional) Description Name of the prompt. Can also refer to the name of an existing prompt page, in which case the prompt page appears when the report is run. Prompt value data type. The default value is string. Prompt values are validated. In the case of strings, the provided value is enclosed in single quotation marks and embedded single quotation marks are doubled. For information about which datatypes are supported, visit the Cognos support Web site (http://support.cognos.com). DefaultText (optional) Text to be used by default. If a value is specified, the prompt is optional. If you use a space and no values are provided in the Prompt Value dialog box, a Where clause is usually not generated. If you use text and no values are provided in the Prompt Value dialog box, a Where clause is usually generated using the default value. Ensure that the text you provide results in a valid SQL statement.

132

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Parameter Text (optional) QueryItem (optional) TextFollowing (optional)

Description Text that precedes any user-provided values, such as, and column1 = .

The prompt engine can take advantage of the Prompt Info properties of the query item. Descriptive information can be shown although the prompt value is a code. The closing parenthesis which is used most often for the promptmany function. It is also useful when the prompt is optional and is followed by hardcoded filters in the SQL statement.

Examples - Select a Country Prompt When a report is run, you want users to be prompted to choose the country for which they want to see data. The following code examples describe how you can use macros to create different prompts.

Mandatory Prompt with No Data Type Specified

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY = #prompt('CountryName')#

Note the following: The Datatype argument is not specified. Therefore, it is a string, which is correct in this case. The DefaultText argument is not specified. Therefore, it is a mandatory prompt.

Mandatory Prompt with the Data Type Specified

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY_CODE > #prompt('Starting CountryCode', 'integer', '', '', '[gosales].[COUNTRY_MULTILINGUAL].[COUNTRY_CODE]')#

Note the following: This prompt requires a valid integer value as response. The DefaultText argument is not specified. Therefore, it is a mandatory prompt.

Optional Prompt and Mandatory Filter with the Data Type and Default Value Specified
select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY_CODE > #prompt('Starting CountryCode', 'integer', '10'

User Guide 133

Chapter 4: Preparing Relational Metadata for Use in Reports

)#

Note the following: This prompt allows the user to supply a valid integer response. The DefaultText argument is specified. Therefore, the user may omit entering a value, in which case the value 10 is used. This makes it an optional prompt, but not an optional filter.

Prompt That Appends Text to the Value

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL #prompt('Starting CountryCode', 'integer', ' ', // < = = this is a space 'where COUNTRY_MULTILINGUAL.COUNTRY_CODE >' )#

Note the following: The DefaultText argument is specified as a space character. In this case, the generated text is just the space character, which eliminates the Where clause from the query. The Text argument is specified, which is written into the generated SQL before the user-provided prompt value.

Syntax Substitution
Select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL #prompt('Sort column', 'token', 'group by COUNTRY', 'group by ' )#

Note the following: The Datatype argument is set to token, which means that the user-provided value is entered into the SQL without any checking on the provided value. Token should be used only if there is a list of pick-values for the user. The DefaultText argument is specified. Therefore, this is an optional prompt and group by COUNTRY is used in the generated SQL.

Examples - Create a Prompt That Uses a Parameter Map

When a report is run, you want users to select a language for the data in the report. The following examples describe several ways you can do this.

Prompt That Uses a Session Variable

select ORDER_METHOD.ORDER_METHOD_CODE as ORDER_METHOD_CODE, ORDER_METHOD.ORDER_METHOD_#$language# as ORDER_METHOD_EN from gosales.gosales.dbo.ORDER_METHOD ORDER_METHOD #prompt($PromptLabels{$language}, '', ' ', 'where ORDER_METHOD.ORDER_METHOD_' + $language + ' >'

134

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

)#

Note the following: The name of the prompt is specified using a lookup in the parameter map named PromptLabels. The key value is the session variable $language. The Where clause is using a parameterized column.

A Parameter Map That Nests Prompts

select ORDER_METHOD.ORDER_METHOD_CODE as ORDER_METHOD_CODE, ORDER_METHOD.ORDER_METHOD_#$language# as ORDER_METHOD_EN from gosales.gosales.dbo.ORDER_METHOD ORDER_METHOD #prompt($DynPromptLabels{'ex9'}, '', ' ', 'where ORDER_METHOD.ORDER_METHOD_' + $language + ' >' )#

Note the following: In the model, there is a parameter map DynPromptLabels with
#$PromptLabels{$language}#

Part of the prompt information is run from a parameter map instead of being coded directly inside the SQL. The whole macro containing the prompt can be a value in a parameter map.

Examples - Create a Multiple Value Prompt

When a report is run, you want users to select one or more values. The following examples describe several ways you can do this.

Prompt with a Required Minimum

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY IN (#promptmany('CountryName')#)

Note the following: The user must enter at least a single value. This resembles the first example on prompting for a country (p. 133).

Prompt with a Required Minimum with the Data Type Specified

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY_CODE IN ( #promptmany('Selected CountryCodes', 'integer', '', '', '[gosales].[COUNTRY_MULTILINGUAL].[COUNTRY_CODE]')# )

Note the following: This resembles the second example on prompting for a country (p. 133). User Guide 135

Chapter 4: Preparing Relational Metadata for Use in Reports

Optional Prompt with the Data Type and Default Value Specified
select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL where COUNTRY_MULTILINGUAL.COUNTRY_CODE IN ( #promptmany('Selected CountryCodes', 'integer', '10' )# )

Note the following: The In clause and both parentheses are part of the SQL statement.

Prompt That Adds Text Before the Syntax

select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL #promptmany('Selected CountryCodes', 'integer', ' ', // < = = this is a space 'where COUNTRY_MULTILINGUAL.COUNTRY_CODE IN ( ', '', ')' )#

Note the following: This example uses the TextFollowing argument.

Optional Prompt That Adds Text Before the Syntax

Select COUNTRY_MULTILINGUAL.COUNTRY_CODE as COUNTRY_CODE, COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, COUNTRY_MULTILINGUAL."LANGUAGE" as LANGUAGE1, COUNTRY_MULTILINGUAL.CURRENCY_NAME as CURRENCY_NAME from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL, gosales.gosales.dbo.COUNTRY XX where COUNTRY_MULTILINGUAL.COUNTRY_CODE = XX.COUNTRY_CODE #promptmany('Selected CountryCodes', 'integer', ' ', ' and COUNTRY_MULTILINGUAL.COUNTRY_CODE IN (', '', ')' )#

Organizing the Model

For information about organizing an SAP BW model, see (p. 185). When you organize the model, you make it easier for your users to find and understand the data in the model. You also make the model easier for you to manage and maintain. We recommend that you create several views, or layers, in the model: Keep the metadata from the data source in a separate namespace or folder.

136

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports In Framework Manager, this is called the import view. Create one or more optional namespaces or folders for resolving complexities that affect querying using query subjects or dimensional objects. To use Analysis Studio or any OLAP-style queries, there must be a namespace or folder in the model that represents the metadata with dimensional objects. Create one or more namespaces or folders for the augmented business view of the metadata that contains shortcuts to dimensions or query subjects. In Framework Manager, these are called the business view. Use business concepts to model the business view. One model can contain many business views, each suited to a different user group. You publish the business views.

Security can be defined in any of the views. It depends on your business requirements. For example, if you need to keep everyone from viewing an object, you add security to the object in the import view. Typically security is applied in the business view. You can create star schema groups (p. 137) include metadata in several folders by using shortcuts (p. 140) create namespaces or folders (p. 141) create query item folders (p. 142) create measure folders (p. 142)

Create a Star Schema Group

Star schema groups can make the model more intuitive for end users by indicating which regular dimensions and measure dimensions are related. Star schema groups can also facilitate multiple-fact reporting by indicating how to use regular dimensions that are common to many measure dimensions. Multiple-fact reporting is also known as cross-functional reporting. Star schema groups also provide context for queries with ambiguous joins. By creating star schema groups in the business view of the model, you can clarify which join path to select when multiple join paths are available. This is particularly useful for fact-less queries. In a star schema design, numeric, transactional data is contained in a central fact table with related dimension tables radiating out from the fact table.

Star schema groups can contain the selected dimensions, query subjects, or shortcuts. The objects in a star schema group cannot reference, or be referenced by, any object outside the group. Therefore, Framework Manager automatically creates a shortcut for any object that is referenced by an object outside the group.

Example - Star Schema

For example, in a project for sales analysis, you include these dimensions: dates of sales (Time) locations of sales (Region) product details (Product) customer information (Customer)

User Guide 137

Chapter 4: Preparing Relational Metadata for Use in Reports You include quantity in the fact table.

A Star Schema Group Based on One Dimension or Query Subject

When you create a group, you can select one or more dimensions or query subjects. Generally, you select a single object when it is a fact that has a relationship to every dimension or query subject that you want in the star schema group. When you create a star schema group that is based on one object, the following occurs: Framework Manager shows a list of objects with which it has relationships so that you can quickly select the objects that you want in the group. The name of the group is based on the name of the fact table. The new group is created under the same parent as the selected object.

A Star Schema Group Based on Multiple Dimensions or Query Subjects

When you create a group, you can select one or more dimensions or query subjects. Selecting multiple dimensions or query subjects is useful if you want to group dimensions or query subjects that do not already have relationships defined. The new group is placed under the nearest common parent of the dimensions or query subjects.

Steps
1. Select one or more dimensions or query subjects. 2. From the Tools menu, click Create Star Schema Grouping. 3. If you want to exclude an object from the group, in the Selected query subjects box, clear the check box next to the object. 4. Choose one of the following: To add shortcuts to the group, click Create a shortcut for all selected objects. To move the objects to the group, click Create shortcuts only for objects that are used outside the star schema. 5. Move the selected objects to a separate namespace: Ensure that the Create a new namespace for this grouping check box is selected. In the Namespace name box, type the name of the new namespace. 6. Click OK. 7. If there are multiple relationships, also known as role-playing dimensions, create relationship shortcuts for them (p. 218), or create individual dimensions or query subjects if you must rename them.

Resolve Multiple Conformed Star Schemas

You will likely see conformed regular dimensions between measure dimensions. Join ambiguity is an issue when you report using items from multiple dimensions without including any items from the measure dimension. This is called a fact-less query. For example, Product and Time are regular dimensions related to the Product forecast and Sales measure dimensions.

138

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports

Using these relationships, how do you write a report that uses only the Product and Year items? The business question could be which products were forecasted for sale in 2005 or which products were actually sold in 2005. Although this query involves only the Product and Time dimensions, these dimensions are related through multiple measure dimensions. There is no way to guess which business question is being asked. You must set the context for the fact-less query. In this example, we recommend that you create two namespaces, one containing Product, Time, and Product forecast, and another containing Product, Time, and Sales.

When you create these namespaces, use the Create Star Schema Grouping wizard to select the correct dimensions for each measure, create shortcuts for all objects, and move the shortcuts to a new namespace. When you do this for all star schemas, you resolve join ambiguity by placing shortcuts to the measure dimension and all regular dimensions in a single namespace. The shortcuts for conformed dimensions in each namespace are identical and are references to the original object. With a namespace for each star schema, it is now clear to the end users which items to use. To create a report on Products Sold in 2005, they use Product and Year from the Sales Namespace. The only relationship that is relevant in this context is the relationship between Product, Time, and Sales Fact, and it is used to return the data.

Steps
1. Select one of the measure dimensions. 2. From the Tools menu, click Create Star Schema Grouping. 3. If you want to exclude a dimension or query subject from the group, in the Selected query subject box, clear the check box next to the dimension or query subject.

User Guide 139

Chapter 4: Preparing Relational Metadata for Use in Reports 4. Click Create a shortcut for all selected objects. 5. Move the selected objects to a separate namespace: Ensure that the Create a new namespace for this grouping check box is selected. In the Namespace name box, type the name of the new namespace. 6. Click OK. 7. Repeat these steps for the other measure dimension.

Model a Snowflaked Dimension as a Star Dimension

A snowflaked dimension removes low-level cardinality attributes from the dimension tables and places them in secondary dimensions that are linked back to the original dimensions by artificial keys. You can model a snowflaked dimension as a star dimension.

Steps
1. Select the query subjects that are required to access the data, and put them in a new namespace (p. 141). 2. Ensure that all relationships are correct (p. 73). 3. Handle multilingual metadata (p. 107). 4. Create a model dimension for each snowflaked dimension: Select the query subjects you need. From the Actions menu, click Merge in New Regular Dimension. When prompted, click Yes to re-create all relationships. Rename the new model dimension. By default, its name is composed of the concatenated names of the original objects. 5. If you require multiple levels, do one of the following: Use the dimension map to define hierarchies and levels for the dimension (p. 79). Specify determinants if the levels are stored in a single query subject (p. 92). You now have a star dimension.

Use Shortcuts
For information about shortcuts for SAP BW metadata, see (p. 185). A shortcut is a reference to an object, such as a relationship, a dimension, a query subject, or a folder. We recommend that you use shortcuts in the business view when there is an overlap between user groups and you want to include the metadata in more than one folder. With shortcuts, you can have multiple references to an object. For example, you create folders named Orders, Products, and Customers. If you want both Orders and Customers to contain the same dimension, you must create a shortcut to the dimension and add it to both folders. If there is more than one shortcut to the same object in the same folder or namespace, the shortcuts act as aliases. When you create a shortcut, Framework Manager does not set the Screen Tip and Description properties. Unless you define these properties, the values shown in the report authoring tools are the same as those defined in the object that the shortcut references. Tip: To go to the object that the shortcut references, right-click the shortcut and click Go To Target. For information about modifying properties, see "The Properties Pane" (p. 19).

Shortcuts and Relationships

When you decide where to place shortcuts, consider how the scope of the shortcut affects relationships.

140

Framework Manager

Chapter 4: Preparing Relational Metadata for Use in Reports Shortcuts in a different folder from the target query subject use the relationships of the target query subject. Shortcuts in the same folder as the target query subject ignore the relationships of the target query subject and use only those specified for the shortcut. You can specify a different relationship for a shortcut than the relationships of the target query subject. By creating relationships from the shortcut to other query subjects, you avoid cross-join errors in the model. You cannot create shortcuts to scope relationships.

Shortcuts and Dimensions or Query Subjects

Shortcuts result in fewer dimensions or query subjects to maintain. You can keep dimensions or query subjects in the import view and keep shortcuts in the business view. When you create a shortcut to a dimension or query subject, you cannot customize which query items are in the shortcut. The entire dimension or query subject is included in the shortcut. Shortcuts are created when star schema groups are created. A fact table and its dimension tables are stored in the import view. If you have multiple star schemas, only one dimension or query subject must exist for a dimension table. All other instances of the dimension or query subject are shortcuts to the original. By using shortcuts, you can build queries involving multiple fact tables that are related through shared dimension tables. The security you specify for an object is passed to shortcuts that reference the secured object. If you have a shortcut to a secured object, only users with permission to see the secured object can see the shortcut in the published package.

Step
Right-click the query subjects, dimensions, or folders that you want to create shortcuts to, and click Create Shortcut or from the Tools menu, click Create Star Schema Grouping.

For information about security, see (p. 202) relationship shortcuts, see (p. 77)

Create a Folder or Namespace

For information about folders and namespaces for SAP BW metadata, see (p. 186). You can create folders to organize objects by subject or functional area. This makes it easier for you to locate metadata in projects that have many query subjects or dimensions. You can nest folders by creating new folders in an existing folder. Tip: When viewing metadata in the Diagram tab, you can expand or collapse folders. From the Diagram menu, click Collapse All or Expand All. When you want to reuse identical objects with the same name, create separate namespaces. If you set security on a folder and then move objects into the folder, confirm that exclusions are set correctly.

Steps
1. 2. 3. 4. From the Actions menu, click Create, Folder. In the Name box, type a name for the new folder. Click Next. Choose whether to create shortcuts to the objects or actually move the objects: To create shortcuts that reference selected objects, click Create a shortcut for the selected items. Do not select all the objects in the namespace to avoid creating a recursive structure in the published package. To move selected objects to the folder, click Move the selected items to the new folder. When you move an object that participates in a relationship, the relationship may also move. User Guide 141

Chapter 4: Preparing Relational Metadata for Use in Reports 5. Select the objects you want to add to the folder. 6. Click Finish. For information about reusing identical objects with the same name, see "Use Separate Namespaces" (p. 28) setting security on a folder (p. 202) relationships, see (p. 73)

Create a Query Item Folder

For information about query item folders for SAP BW metadata, see (p. 186). You can create query item folders to organize query subjects or dimensions that contain a large number of query items. A query item folder can contain only query items and query item folders.

Steps
1. In the Project Viewer pane, click a query subject or dimension. 2. From the Actions menu, click Create, Query Item Folder. A new query item folder appears in the Project Viewer, under the query items that belong to that query subject or dimension. 3. Drag the query items that you want into the query item folder. You cannot add query items that do not exist in the parent query subject or dimension.

Create a Measure Folder

For information about measure folders for SAP BW metadata, see (p. 187). You can create measure folders to organize measure dimensions that contain a large number of query items. You can nest measure folders within other measure folders. You cannot create a measure folder from a measure shortcut.

Steps
1. In the Project Viewer pane, click a measure dimension. 2. From the Actions menu, click Create, Measure Folder. A new folder appears in the Project Viewer, under the measures that belong to that measure dimension. 3. Drag the query items that you want into the measure folder. You cannot add measures that do not exist in the parent measure dimension.

142

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

After importing metadata, you must ensure that it is set up to meet your users' reporting requirements, and provide any additional information that they require. Enhancements you make in Framework Manager do not affect the original data source. Tip: To verify that the model meets the reporting requirements, you can select objects that will appear in a report and test them. The test results show you the report that your users will see. Or you can publish a package at any time and then use the package to create reports. You can check the project at any time to ensure that the references between the objects it contains are valid. You can adjust settings in Framework Manager and the report authoring tools to optimize performance (p. 187). Note: Information on relational metadata is in "Preparing Relational Metadata for Use in Reports" (p. 73).

Import View
To ensure that the metadata is set up correctly in the import view, do the following: Work with dimensions (p. 144).

For multiple SAP BW Query or InfoCube models, conform dimensions (p. 151). Work with multilingual metadata (p. 161). Control how data is used and formatted by checking query item properties (p. 164). Business View
To enhance the metadata in the business view, do the following: Add model query subjects (p. 155).

Add business rules, such as calculations, filters, and prompts, that define the information

users can retrieve (p. 171). Organize the model by creating separate views for each user group that reflect the business concepts familiar to your users (p. 185).

Mapping SAP BW Objects to Framework Manager

SAP BW objects are mapped to the following Framework Manager objects. SAP BW object Query, InfoCube, RemoteCube, MultiCube Framework Manager object Namespace

User Guide 143

Chapter 5: Preparing SAP BW Metadata for Use in Reports

SAP BW object Characteristic

Framework Manager object Dimension containing hierarchies representing each of the presentation hierarchies. The default hierarchy contains two levels representing the aggregation of all characteristic values, also known as the All value all characteristic values Note: By default, Framework Manager imports SAP BW Currency and Unit of Measure characteristics. You can remove these characteristics if you do not need them.

Dimension Key figure Presentation hierarchy level

Dimension Query item that is part of a measure dimension called Key Figures Level Note: Level names must be defined in the Administrator Workbench to be meaningful. Query item associated with a level whose Usage property value is set to Attribute. Data source property For information about the SAP BW variables that Framework Manager supports, see (p. 177)

Attribute SAP BW variable

For information about setting access privileges to retrieve metadata from SAP BW, see "Access to SAP BW Metadata and Data" (p. 30).

Working with Dimensions

For information about dimensions based on relational metadata, see (p. 78). A dimension is a broad grouping of descriptive data about a major aspect of a business, such as products, dates, or markets. The types of dimensions that you can work with in Framework Manager are regular dimensions and measure dimensions. In SAP BW, measure dimensions are called key figures. Each regular dimension consists of one or more hierarchies that typically contain several levels. For example, in a project for sales analysis, you include these dimensions: Name Time Region Product Customer Sales Type Regular dimension Regular dimension Regular dimension Regular dimension Key Figures dimension Description Dates of sales organized into years, quarters, months, weeks, and days when sales were made Locations of sales grouped into sales regions, countries, and cities Product details organized by product type, brand, model, color, and packaging Customer information Purchase details such as units sold, revenue, and profit

144

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Modify a Regular Dimension

For information about creating a regular dimension for relational metadata, see (p. 78). A regular dimension contains descriptive and business key information and organizes the information in a hierarchy, from the highest level of granularity to the lowest. It usually has multiple levels and may have multiple key segments to define a level. It may also have multiple hierarchies. Only a single hierarchy can be defined on a data source regular dimension or any regular dimension that participates directly in a relationship. Use regular dimensions to organize and present descriptive information to guide the end user experience in the report authoring tools. When dimensions are based on SAP BW metadata, you cannot edit the underlying query.

Steps
1. Click the regular dimension you want to modify. 2. From the Actions menu, click Edit Definition. 3. Choose the action that you want: Embed calculations by clicking Add and then defining the expression (p. 172). To change a calculation that has been embedded in the dimension, in the Dimension Map tab, click Attributes, right-click the query item, and click Edit Expression. Embed filters (p. 174). Test the dimension (p. 152). Conform (p. 151) or remove conformed dimensions (p. 152). 4. Click OK.

Hierarchies for a Regular Dimension

For information about hierarchies for relational metadata, see (p. 81). A hierarchy is an ordered list of levels or a collection of items. Each query item in a hierarchy must have a unique name. Only a single hierarchy can be defined on a data source regular dimension or any regular dimension that participates directly in a relationship. Multiple hierarchies occur when different structural views can be applied to the same data. The first hierarchy is the primary or default hierarchy. You cannot use the hierarchies from a single dimension in the same report. For example, sales staff can be viewed by manager or by geography and can be modeled as a single dimension with two hierarchies.

Tip: To change the default hierarchy for a dimension with multiple hierarchies, in the Properties pane, click the ellipsis (...) button in the Default Hierarchy box, select a different hierarchy, and click OK.

Balanced Hierarchy
Each path in a balanced hierarchy descends to the same depth.

User Guide 145

Chapter 5: Preparing SAP BW Metadata for Use in Reports For example, in the following diagram, the highest level is Product Line. Level 2 is Product Type. Level 3 is Products.

In SAP BW, all leaf nodes of a hierarchy are values of the characteristic, but each path does not have to descend to the lowest level of the hierarchy.

Unbalanced Hierarchy
The branches in an unbalanced hierarchy descend to different levels. For example, in the following diagram, the highest level in an organization is the CEO. Level 2 is the vice-presidents and the CEOs executive assistant. The executive assistant does not have subordinates although the vice-presidents do.

An unbalanced hierarchy can also be ragged. In a ragged-unbalanced hierarchy, there are gaps in the levels and the levels descend to different depths. In SAP BW, this occurs only when there are "not assigned" (or "#") nodes in a presentation hierarchy. However, the presence of such a node does not guarantee that the hierarchy is unbalanced. You must investigate the layout of a hierarchy to be certain.

Ragged Hierarchy
At least one path in the hierarchy skips at least one level. For example, the highest level could be Continent. Level 2 could be Country. Level 3 could be City. Level 4 could be Street. A country such as Vatican City contains only streets, no cities.

146

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

In SAP BW, this occurs only when there are not assigned or # nodes in a presentation hierarchy. However, the presence of such a node does not guarantee that the hierarchy is ragged. You must investigate the layout of a hierarchy to be certain.

Network Hierarchy
A member of the hierarchy has more than one parent. For example, an employee may report through different organizations and have multiple managers. For SAP BW, this employee will be included in the count of all employees only once, and not be included in every organization.

In addition to hierarchies in dimensions, there are hierarchies in SAP BW metadata (p. 147).

SAP BW Hierarchies
When importing metadata, Framework Manager generates a dimension for each SAP BW characteristic. Only one hierarchy associated with a given characteristic can be used in a report. Therefore, you should group dimensions that represent the hierarchies of a single characteristic into a folder or model query subject to make reporting easier for report authors. If there are multiple hierarchies in an SAP BW data source, the first hierarchy that is imported becomes the default hierarchy. Framework Manager supports the following types of hierarchies: characteristic This is a list of all the characteristic values. text node Non-leaf nodes contain only text and do not reference any other data source object. characteristic value The nodes of each level of a presentation hierarchy are values from another characteristic.

User Guide 147

Chapter 5: Preparing SAP BW Metadata for Use in Reports recursive The nodes of the entire presentation hierarchy are from the characteristic itself.

Framework Manager does not support hierarchies that contain two or more types of nodes. These hierarchies are imported but are hidden in the Framework Manager model. Because hierarchical metadata is automatically generated for SAP BW, you cannot change it in Framework Manager.

Versioned Hierarchies
You can import the following types of versioned hierarchies from an SAP BW data source: Version dependent hierarchy A hierarchy can have multiple versions. Each version of a hierarchy can have a different structure, such as Sales by Region and Sales by Manager. During metadata import, Framework Manager identifies each version as a separate hierarchy and creates a dimension for each. Entire hierarchy time dependent Each version has an associated time period that does not overlap with any other version of the same hierarchy. The structure of each version can be different. During metadata import, Framework Manager identifies each version as a hierarchy and includes the applicable time period as part of the dimension name. Time-dependent hierarchy structure There is a single version of the hierarchy, but nodes within the hierarchy can be assigned applicable time periods. Over time, the structure of the hierarchy can change with new levels being introduced or removed. For example, levels that represent different sales districts can be added over time. During metadata import, Framework Manager identifies a time-dependent hierarchy structure as a non-versioned hierarchy and recognizes the structure of the hierarchy as of the current date. The type of dimension determines which hierarchy is used and, for time-dependent hierarchies, which date to use to control the version. Framework Manager sets the query key date of time-dependent hierarchies based on dates that are contained within the time-dependent hierarchy. You can then select specific versions of hierarchies. For hierarchies with versions on time, the default is the current date and time. The hierarchy that you apply to a characteristic depends upon the type of query key date: fixed, current, or variable. The query key date is set for a specific date. For fixed date, include only the version that corresponds to the fixed date in the underlying SAP BW Query. For example, if the BEx query has a fixed date such as 2005, only 2005 is imported. For current date, include only the version that encompasses a time span appropriate for the present until some reasonable time in the future. For variable, set the date for the variable in Framework Manager and include only the version of the hierarchy applicable to that date. When you use Framework Manager to model SAP BW data, any versions or dates applied to a presentation hierarchy in BEx are not imported into the model. Therefore, all versions of the hierarchy are accessible in Framework Manager. You may have a time-dependant hierarchy and a variable defined in BEx to establish the effective date for the hierarchy. In this case, assign a fixed date to the variable in Framework Manager and include only the dimension that corresponds to that date in the model. In Framework Manager, if a versioned hierarchy is not time-dependent and has a fixed version, include only the version of the hierarchy associated with the selected version. Otherwise the report author is presented with a hierarchy that is inaccessible.

Levels for a Regular Dimension

A level is a collection of attributes or query items, typically of a common granularity. Each level needs an item that is defined as a key and another item that is defined as a caption.

148

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports The first level of the hierarchy is automatically defined as the All level. It contains a single root member, which represents the top level of the hierarchy. For example, the All level for the Time dimension is named Time (All). You cannot delete or move the All level. You can change its name, description, and screen tip.

Keys for Levels

A key is a query item that uniquely identifies members in a level. For example, Product Number uniquely identifies a product while City, State, and Country are all needed to uniquely identify a city. The key may or may not be contained in a level. Foreign keys are used to relate the measure dimension to its regular dimensions. Each level needs an item that is defined as a key.

Specify Roles
For information about roles for relational metadata, see (p. 83). Roles define what appears in the member tree in the report authoring tools. Use roles to organize and manage metadata and to determine how to present data to your users. You can also create expressions that refer to roles instead of query items. You must use the roleValue function to refer to a particular role. For example, you want to query against a specific role in a hierarchy but the query item playing that role is different at each level of the hierarchy. A single query can span the different query items at each level. You can also use the roleValue function when you know the role but not the underlying query item. You can assign multiple roles to one query item, but the same role cannot be assigned to different query items in the same level. Default roles are pre-defined for all parent-child hierarchies and for all levels in level-based hierarchies. Most of these roles are not visible in the report authoring tools. The roles that are reserved by Cognos 8 start with an underscore. You cannot define a custom role whose name starts with an underscore. The default roles include the following: _businessKey Represents the key for the level. This role is also used to drill through from one data source to another because the business key should be consistent across your organization. The _businessKey role can be assigned to only one attribute in a level. _dimensionUniqueName Returns the name of the dimension as defined in the Framework Manager model. _hierarchyUniqueName Returns the name of the hierarchy as defined in the Framework Manager model. _levelLabel Returns the label that is assigned to the level. _levelNumber Returns the number for the level. _levelUniqueName Returns the name that is assigned to the level. _longName Is assigned to the query item that represents the long name for a level. _memberCaption Presents the caption for a member that will be shown in the report authoring tools. _memberDescription Returns the description for a member within a dimension. _memberUniqueName Returns the Cognos member unique name. _parentUniqueName User Guide 149

Chapter 5: Preparing SAP BW Metadata for Use in Reports Defines the name that is assigned to the parent of the selected query item. _rollupType Defines how a query item is aggregated. _shortName Is assigned to the query item that represents the short name for a level.

If a query item uses a default role, you cannot change its role. This applies to SAP BW metadata only. Each role that you create must have a unique name. You can translate the custom roles in the model. User-defined properties in OLAP data sources are assigned roles with the same name as the query item.

Steps
1. 2. 3. 4. 5. 6. 7. 8. 9. Click the dimension whose roles you want to define. From the Actions menu, click Edit Definition. Click the Dimension tab. In the Hierarchies box, click the level you want. In the Select a level in the hierarchy control to see the query items box, click a query item. Under Role, click the ellipsis (...) button. Click the Custom Roles tab, and click Add. Click Close. Click OK.

You can also use the Dimension Map tab to define roles. Click Attributes, right-click the query item, and click Edit Roles.

Modify a Key Figures Dimension

For information about creating a measure dimension for relational metadata, see (p. 84). A key figures dimension is a collection of facts such as Quantity Sold or Price. Key figures are related to each other through the regular dimensions. When used in a report or analysis, the key figures dimension shows the value of the query item such as a name or number, or shows null, zero, or invalid. To create reports that fully compare and contrast functional areas, you may need to use more than one key figures dimension in a report. You can add value by embedding calculations based on existing business rules, such as Profit Margin. You cannot define hierarchies or levels for a key figures dimension. When dimensions are based on SAP BW metadata, you cannot edit the underlying query. However, you can add calculations and filters.

Steps
1. Click the measure dimension you want to modify. 2. From the Actions menu, click Edit Definition. 3. Choose the action that you want: Embed calculations by clicking Add and then defining the expression (p. 172). To change a calculation that has been embedded in the dimension, in the Dimension Map tab, click Attributes, right-click the query item, and click Edit Expression. Embed filters (p. 174). Test the dimension (p. 152). 4. Click OK.

150

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Conform SAP BW Dimensions

When you import multiple SAP BW Queries or InfoCubes, there can be two or more hierarchies that contain the same information.

You can conform these hierarchies in Framework Manager to create one dimension and one or more shortcuts. These hierarchies must have the same levels and properties. However, the order of the properties can be different. By conforming dimensions, the report author can create reports that use multiple cubes without using an SAP BW MultiProvider. A conformed dimension is represented by a dimension with one or more shortcuts to it. The dimension contains a list of data sources in which the dimension exists. If you want to retrieve data from a specific data source, ensure that you import the dimension from this data source before all others.

The dotted line in the diagram indicates a shortcut. We do not recommend conforming time or date dimensions because values in the dimensions are often not the same across cubes, and this can produce errors and invalid reports. For example, a project contains three SAP BW Queries. One SAP BW Query contains basic information with dimensions and key figures, one contains the same information with variables applied, and one contains the same information with currency conversions applied. The common dimensions can be conformed allowing the modeler to maintain one set of common dimensions rather than three sets. To simplify your model, create a business view that uses one set of conformed dimensions, and create individual Key Figure dimensions to reflect the three different SAP BW Queries: Key Figures, Key Figures with Variables, and Key Figures with Currency Conversion. When conforming dimensions, consider the scope of object-based security (p. 202).

Steps
1. Select one or more dimensions that you want to conform. 2. From the Tools menu, click Generate Conformed Dimensions. The Generate Conformed Dimensions wizard appears, listing all dimensionally aware SAP BW dimensions that exist in the model. 3. Select the appropriate areas containing the dimension that you want to conform with, or select the actual dimension. User Guide 151

Chapter 5: Preparing SAP BW Metadata for Use in Reports If you want queries based on these dimensions to retrieve data from a specific data source, select the dimension that references the preferred data source. 4. Click Next. 5. Identify the dimensions that you want to include in the conformed dimension, and click Next. 6. Click Finish.

Remove a Conformed SAP BW Dimension

When you import SAP BW metadata into your project, you can select an option for Framework Manager to automatically create conformed dimensions for any two or more hierarchies that have a matching structure. If there are dimensions that you do not want conformed, you can remove them after the initial import.

Steps
1. Delete all instances of the dimension from the model. Tip: The easiest way to do this is to delete the one instance of the dimension that is not a shortcut. This removes all the shortcuts from the project. 2. From each relevant data source, re-import the dimensions that were deleted, ensuring that the generate conformed dimensions option is not selected. 3. Ensure that dimensions appear in the project as expected. No shortcuts should be used for these dimensions.

Explore Dimensions
For information about exploring dimensions for relational metadata, see (p. 86). You can explore a visual representation of the objects that are connected to the query subject or dimension that you select in the Project Viewer. The Context Explorer shows the objects that the selected object is connected to. You can select a connected object and see its references too. You can hide an object in the Context Explorer. You can also change the layout, fit all objects in the Context Explorer, and zoom in and out. You can also use the Dimension Map tab to explore dimensions.

Steps
1. Select one or more objects that you want to explore. 2. From the Tools menu, click Launch Context Explorer. 3. To see the connected objects, click one or more objects and click the appropriate button. Goal View the objects that are related to the selected object. View the immediate references for the objects. Available only for regular dimensions and measure dimensions. View all references for the objects. Available only for dimensions and measure dimensions. 4. If you want to see details about an object, such as its relationships and query items, right-click the object, click Level of Detail, and then select the details that you want to see. For information about creating a dimension from the Dimension Map, see (p. 145). Button

Test a Dimension, Query Subject, or Query Set

For information about testing relational metadata, see (p. 86).

152

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports Testing a regular dimension returns the attributes associated with the first hierarchy encountered in the dimension. You can see the results that an object returns by testing it. You can test when creating an object or later on. The objects you can test are dimensions, query subjects, query sets, hierarchies, levels, calculations, and query items. You can test a specific report before publishing a package by selecting and testing the objects that will appear in the report. This makes it easier to debug a model and to verify that the model meets the reporting requirements because you do not need to create and publish packages first. When you test an object, Framework Manager returns sample data. Formatting is not applied to the sample data. If you must test formatting, you must publish the package and view the objects in the report authoring tools. You can change existing test settings to customize the results that the test shows. For example, in addition to other settings, you can control the number of rows returned.

Steps When Creating or Modifying an Object

1. Select the object you want to test. 2. From the Actions menu, click Edit Definition, and click the Test or Query Information tab. The Test Results box is initially empty until you run the query. Any result sets that contain Binary Large Objects are shown as [blob]. 3. To run the query and bring back all the test results, click Test Sample. 4. Choose the option that you want. Goal Add a count of the rows Process all records at one time instead of one page at a time Group and total measures Obtain more information about the query results 5. Click OK. Action Click Total Rows. Select the Batch check box. Select the Auto Sum check box. Click the Query Information tab.

Steps to Test a Specific Report

1. Select the object or objects that will appear in the report. 2. From the Tools menu, click Test. A message appears, telling you if the test was successful or if problems were found. 3. To view details about any problem that is found, click the Query Information tab. If you do not see the results of the query in the test window, the data from your data source may exceed the value of the Runtime Limits governor. The query stops at the specified limit, but the test result window does not contain any data. Tip: Set the Runtime Limits governor to zero. For more information about the Context Explorer, see "Explore Dimensions" (p. 152).

Change the Test Settings

You can customize the tests by changing the test settings.

Steps
1. Select the object that you want. 2. From the Actions menu, click Edit Definition and then click the Test tab or the Query Information tab. 3. Click Options and then click the Test Settings tab.

User Guide 153

Chapter 5: Preparing SAP BW Metadata for Use in Reports 4. Choose the options that you want. Goal Restrict the number of rows that are returned Action Persistence

Select the Restrict the This setting applies to all maximum number of rows to dimensions, query subjects, and be returned check box and type query sets in the model. the required number of rows This setting is saved and used in your next session with any model. Drag the Level of Information This setting is saved and used in shown in Results Information your next session with this model. slider to the location that represents the amount of detail you require The override values are not saved with the model. This setting is for your current session only.

Specify the level of detail

Temporarily override In the Session Parameters box, session parameters click Set. The Session Parameters dialog box appears. Apply relevant design mode filters Select the Apply all relevant design mode filters when testing check box. This applies all relevant filters whose usage is set to design mode in another dimension, query subject, or query set. Apply a security filter Change the prompt values In the Security Filters box, click Edit. In The Current Prompt Values box, click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model. 5. Click OK two times. For information about working with dimensions, see (p. 144). working with query subjects, see (p. 155).

This setting is saved and used in your next session with any model.

The prompt values are not saved with the model. This setting is for your current session only.

Modify Multiple Objects at Once

For information about relational metadata, see (p. 88). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order.

154

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show. 4. Make any changes to the values of the property.

Working with Model Query Subjects

For information about query subjects based on relational metadata, see (p. 89). A query subject is a set of query items that have an inherent relationship. You use Framework Manager to modify query subjects to optimize and customize the data that they retrieve. For example, you can add filters or calculations. When you change the definition of a query subject, Framework Manager regenerates the associated query items, ensuring that any changes to query subject properties are reflected in all query items for that query subject. For SAP BW metadata, you can work with model query subjects in Framework Manager. Model query subjects are not generated directly from a data source but are based on query items in other query subjects or dimensions, including other model query subjects. By using model query subjects, you can create a more abstract, business-oriented view of a data source. Usually, model query subjects are created in the business view, not the import view. You cannot combine query items from different dimensions in one model query subject for SAP BW metadata. If you create a model query subject containing multiple dimensions, you may encounter problems when using the model query subject in conjunction with other query subjects or dimensions. Ensure that the items in a model query subject do not contravene the logic of the model, for example, the product item inserted between the country and city items. Test the model query subject in a report; if grouping works, the model query subject is valid. For information about creating model query subjects, see (p. 155) or (p. 156).

Create a Model Query Subject

For information about model query subjects based on relational metadata, see (p. 90). For SAP BW metadata, you can create only a model query subject. You can also create a new model query subject by merging existing query subjects and query items (p. 156).

Steps
1. Select the namespace folder and, from the Actions menu, click Create, Query Subject. 2. In the Name box, type a name for the new query subject. 3. Click the Model Query Subjects and Query Items button, and click OK. The Query Subject Definition dialog box appears. 4. Click the Query Subject Definition tab. 5. From the Available Model Objects box, drag the items for this model query subject to the Query Items and Calculations box. 6. To embed calculations in the model query subject, click Add and define the calculation. 7. To embed filters in the model query subject, click the Filters tab. 8. To test the model query subject, click the Test tab. 9. Click OK. 10. To use a star layout in the Diagram view, from the Diagram menu, click Auto Layout Diagram, and then select Star. Tip: To control the model area that is visible in the diagram, click and hold the overview button in the bottom right corner and drag the pointer over the diagram. For information about

User Guide 155

Chapter 5: Preparing SAP BW Metadata for Use in Reports embedded calculations, see (p. 172). embedded filters, see (p. 174). testing and setting test options, (p. 159).

Create a Model Query Subject Based on Existing Objects

For information about model query subjects based on relational metadata, see (p. 95). You can select existing model objects and merge them into a new model query subject. This means that you can reuse existing metadata to quickly create query subjects. The objects that you can merge include relational data source query subjects and their shortcuts model query subjects and their shortcuts query items, filters, and calculations in model and data source query subjects relationships and relationship shortcuts between model and data source query subjects You can merge any number of the same type of objects into a new query in a single operation. The merge always creates a new model query subject. Framework Manager generates the name of the new query subject by appending the name of the first query subject to the name of the last query subject. A unique number is appended to duplicate query item names. You are prompted to re-create any existing relationships between the original query subjects and query subjects that are not included in the merge. However, to avoid self-joins, any relationship that exists between the query subjects being merged is ignored. When you merge query items, only the relationships that the items participate in are replicated. The new query subject contains any filters that exist in the original query subject.

Notes:
Ensure that model query subjects do not contravene the logic of the model. For example, if a query subject with multiple characteristics is used in combination with other query subjects, there can be problems when you run the report. Do not include query items from different query subjects or hierarchies from the same dimension. This causes a run-time error.

Steps
1. Ctrl+click the objects that you want to merge into a single query subject. 2. From the Actions menu, click Merge in New Query Subject. If the query subjects are joined to other query subjects, you are prompted to re-create relationships with the new query subject. 3. If prompted to re-create relationships, click Yes.

Explore Query Subjects

For information about exploring relational query subjects, see (p. 96). You can explore a visual representation of the objects that are connected to the query subject or dimension that you select in the Project Viewer. The Context Explorer shows the objects that the selected object is connected to. You can select a connected object and see its references too. You can hide an object in the Context Explorer. You can also change the layout, fit all objects in the Context Explorer, and zoom in and out. You can also use the Dimension Map tab to explore dimensions.

Steps
1. Select one or more objects that you want to explore. 2. From the Tools menu, click Launch Context Explorer.

156

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports 3. To see the connected objects, click one or more objects and click the appropriate button. Goal View the objects that are related to the selected object. View the immediate references for the objects. Available only for regular dimensions and measure dimensions. View all references for the objects. Available only for dimensions and measure dimensions. 4. If you want to see details about an object, such as its relationships and query items, right-click the object, click Level of Detail, and then select the details that you want to see. Button

Create a Query Set

For information about creating query sets for relational metadata, see (p. 96). A query subject can be defined using the set operations of union, intersect, or except. You define a query set to merge, compare, or equate similar data from different sources. Query sets are useful when modeling data from disparate systems. There are many reasons for creating a query set. A query set may be needed to create a conformed dimension across disparate sources. Or, you may want to compare the contents of two tables to determine whether the tables contain the same data; this is common in test environments. Or, you may want to compare tables with nulls. Or, you want to handle a fact-to-fact relationship. A query set can consist of only two query subjects. You can create a query set that merges two other query sets together. A query set can contain all the rows of two query subjects (union operation) For example, your company recently acquired another company and you need a complete list of all customers. only the rows that are shared between the query subjects (intersect operation) For example, you want to find out which staff members are also managers. only the rows that are different between the query subjects (except operation) For example, you want to highlight the differences between where your products were sold this year and ten years ago. Relationships between the two query subjects in the query set and other query subjects are not included in the query set. The names of the items in the projection list default to the items assigned to the first query subject in the set operation. Not all data types are supported. Generally, sets are not permitted on BFILE, BLOB, CLOB, LONG, and VARRAY data types, or on nested table columns. Reports show different results depending on which operator is used. For example, you have two query subjects with the names of various employees. One contains these rows: Jane, John, John, Patrick. The second contains these rows: Jane, John, John, Michael, Michael. You create a query set. Operator Union Intersect Result Jane, John, Michael, Patrick Jane, John Notes All items are shown. Values are not duplicated. Items in common are shown. Values are not duplicated.

User Guide 157

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Operator Except Union All Intersect All Except All

Result Michael, Patrick Jane, Jane, John, John, John, John, Michael, Michael, Patrick Jane, Jane, John, John, John, John Michael, Michael, Patrick

Notes Items that are not common are shown. Values are not duplicated. All items are shown. Values are duplicated. Items in common are shown. Values are duplicated. Items that are not common are shown. Values are duplicated.

Steps
1. Select two query subjects that meet these requirements: Each query subject must have the same number of columns. Columns must be in the same order. Columns must have the same or similar data types. The data types do not need to be exactly the same if those in the second result set can be automatically converted by the data source to data types compatible with those in the first result set. For example, one query subject contains country data and uses int as the data type. Another query subject contains country data and uses smallint as the data type. Framework Manager imports these query subjects as int16 and int32 and performs a set operation. 2. From the Actions menu, click Define Query Set. 3. Click the Definition tab. 4. In the Name box, give the query set a name. The Query Subject boxes show the order that the query subjects will appear in the Select clause. The order in the Select clause could be important if you want a specific set of column names (aliases) that appears in only one of the query subjects. If the order is incorrect, cancel this query set and start again. For union and intersect, the order of the query subjects does not matter. You can change the order and receive the same answer. For except, the order of the query subjects does matter. 5. Use the Operator box to define how the rows of the query subjects are combined. Option Union Intersect Except Description Retrieves all unique rows from both sets. Duplicates are removed. Retrieves rows that are common between the query subjects. Retrieves rows that are not common between the query subjects.

6. Choose the action that you want. Goal Create a Union All, Intersect All, or Except All operation Action Clear the Remove Duplicate Row check box.

Work with the calculations that are Click the Calculations tab. embedded in the query subjects You can add or edit the calculations and change the order of the calculations.

158

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Goal Work with the filters that are embedded in the query subjects

Action Click the Filters tab. You can add or edit the filters, change the order of the filters, and change the usage of filters. Click the Test tab.

Test the query set 7. Click OK.

For information about embedded calculations, see (p. 172). embedded filters, see (p. 174). testing the query set or changing the test settings, see (p. 159).

Test a Query Subject, Query Set, or Dimension

For information about testing relational metadata, see (p. 98). You can see the results that an object returns by testing it. You can test when creating an object or later on. The objects you can test are dimensions, query subjects, query sets, hierarchies, levels, calculations, and query items. You can test a specific report before publishing a package by selecting and testing the objects that will appear in the report. This makes it easier to debug a model and to verify that the model meets the reporting requirements because you do not need to create and publish packages first. When you test an object, Framework Manager returns sample data. Formatting is not applied to the sample data. If you must test formatting, you must publish the package and view the objects in the report authoring tools. You can change existing test settings to customize the results that the test shows. For example, in addition to other settings, you can control the number of rows returned.

Steps When Creating or Modifying an Object

1. Select the object you want to test. 2. From the Actions menu, click Edit Definition, and click the Test or Query Information tab. The Test Results box is initially empty until you run the query. Any result sets that contain Binary Large Objects are shown as [blob]. 3. To run the query and bring back all the test results, click Test Sample. 4. Choose the option that you want. Goal Add a count of the rows Process all records at one time instead of one page at a time Group and total measures Obtain more information about the query results 5. Click OK. Action Click Total Rows. Select the Batch check box. Select the Auto Sum check box. Click the Query Information tab.

Steps to Test a Specific Report

1. Select the object or objects that will appear in the report. 2. From the Tools menu, click Test. A message appears, telling you if the test was successful or if problems were found. 3. To view details about any problem that is found, click the Query Information tab. User Guide 159

Chapter 5: Preparing SAP BW Metadata for Use in Reports If you do not see the results of the query in the test window, the data from your data source may exceed the value of the Runtime Limits governor. The query stops at the specified limit, but the test result window does not contain any data. Tip: Set the Runtime Limits governor to zero. For more information about the Context Explorer, see "Explore Query Subjects" (p. 156).

Change the Test Settings

You can customize the tests by changing the test settings.

Steps
1. Select the object that you want. 2. From the Actions menu, click Edit Definition and then click the Test tab or the Query Information tab. 3. Click Options and then click the Test Settings tab. 4. Choose the options that you want. Goal Restrict the number of rows that are returned Action Select the Restrict the maximum number of rows to be returned check box and type the required number of rows Persistence This setting applies to all dimensions, query subjects, and query sets in the model. This setting is saved and used in your next session with any model.

Specify the level of detail

Drag the Level of Information This setting is saved and used in shown in Results Information your next session with this model. slider to the location that represents the amount of detail you require The override values are not saved with the model. This setting is for your current session only.

Temporarily override In the Session Parameters box, session parameters click Set. The Session Parameters dialog box appears. Apply relevant design mode filters Select the Apply all relevant design mode filters when testing check box. This applies all relevant filters whose usage is set to design mode in another dimension, query subject, or query set. Apply a security filter Change the prompt values In the Security Filters box, click Edit. In The Current Prompt Values box, click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model. 5. Click OK two times. For information about security filters, see (p. 200). temporarily overriding session parameters, see (p. 184). 160 Framework Manager

This setting is saved and used in your next session with any model.

The prompt values are not saved with the model. This setting is for your current session only.

Chapter 5: Preparing SAP BW Metadata for Use in Reports changing prompt values, see (p. 176). working with query subjects, see (p. 155). working with dimensions, see (p. 144).

Modify Multiple Objects at Once

For information about modifying relational objects, see (p. 100). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order. 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show. 4. Make any changes to the values of the property.

Validate a Model Query Subject

For information about validating relational query subjects, see (p. 100). After you change the definition of a query subject by adding new query items or changing the parameters, you can validate the definition of the query subject without having to open the Query Subject Definition dialog box. You can also validate a query subject when the definition of query subjects that it depends on changes. The Evaluate command completes an exhaustive check of all query subjects and ensures that they can run. When Framework Manager evaluates a query subject, a request is sent to the SAP BW data source. Physical attributes, such as data type, are then updated as needed for the query subject. You can also synchronize the entire project (p. 55).

Steps
1. Select the query subject you want to evaluate. 2. From the Tools menu, click Evaluate Object. If you changed the Regular Aggregate property to unsupported, the property is reset when you evaluate the query subject. If the property is set to any other value, the property is not changed.

Supporting Multilingual Metadata

For information about multilingual relational metadata, see (p. 107). For models that are published in multiple languages, you can view and modify model objects in the different languages. We recommend that you handle multilingual support in the import view so that you can reduce the number of query items contained in each dimension and query subject With fewer dimensions, query subjects, and query items, the model is more manageable. simplify maintenance Multilingual work is done in one place instead of in different business views. ensure consistency Languages are set up correctly for all modelers to use. This is particularly important for segmented models. Modelers will not set up languages in their own way.

User Guide 161

Chapter 5: Preparing SAP BW Metadata for Use in Reports If you are using an SAP BW data source, we recommend that you select the languages for your project when you import the metadata. You can add languages to your project later, but you cannot go back and import the language-specific metadata from the data source. The language-specific metadata would have to be added manually.

Use a Macro to Define SAP BW Currency

When modeling SAP BW metadata, you can use a macro to dynamically substitute SAP BW currency values when the report is run. The target language is defined when you import metadata. An SAP BW Query contains a currency translation table. You can prompt users to select a language. Or you can use a macro to set the language automatically based on the user's locale.

Steps
1. Create a parameter map that contains the following: keys that reflect the ISO standard for the supported model languages, such as EN-en corresponding values that match the ISO standard for the SAP BW currency, such as USD A sample currency translation file exists in the sample database. For more information, see "Create a Parameter Map" (p. 183). 2. In the data source property list, select SAP BW Variables. 3. In the Use Default Value property, set the value to true. 4. In the Default Low Value property, enter a macro that uses the parameter map you created, such as #$CurrencyMap[$runLocale]#

Add a Language to a Project

For information about adding a language when using relational metadata, see (p. 108). You can add a language to a project at any time. For example, you do this if the values for a language were not translated earlier. When you add a language to a project, Framework Manager generates a new property value for every multilingual property of each object in the project. A multilingual property is any text property that appears in a report, such as Name, Description, and Screen Tip. The new values that Framework Manager assigns to these text properties are a combination of the original property value preceded by the language code. For example, if a dimension is named Country, and you add the Dutch language, Framework Manager inserts a name whose value is (nl)Country. Each project contains two types of language definitions: design language This is the language in which the model was originally created. This value is stored in the model and cannot be changed. It serves as the default language value. active language This is the language in which model content is currently shown. When you open a model, the active language is set to the language in the model that most closely matches the region and language settings of the computer. You can change this value at any time for your current session only. In future sessions, the model continues to open in the design language. Note: If you are using an SAP BW data source, we recommend that you select the languages for your project when you import the metadata. You can add languages to your project later, but you cannot go back and import the language-specific metadata from the data source. The language-specific metadata would have to be added manually.

Steps
1. From the Project menu, click Languages, Define Languages. 2. In the Available languages box, select each language you want to add and click the arrow button to move it to the Project languages box.

162

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports Tip: To remove a language, select it in the Project languages box and click the arrow button to move it to the Available languages box. 3. If you want to change the active language, in the Project languages box, click a language and click Set as Active. 4. Click OK. At the prompt, accept the changes you made to the project. 5. Click OK. Tip: To show multilingual property values in the Properties pane, click the Languages tab.

Export a Translation Table

For information about translation tables and relational metadata, see (p. 109). You can generate and export a translation table to simplify the task of translating model objects. The translation table contains a list of all the text strings defined for multilingual properties, such as Name, Description, and Screen Tip. Translators can then use an external application, such as Microsoft Excel, to type the required information in the table. You can export a translation table as either a comma-separated value file (.csv) or Unicode text file (.txt). You must export the translation table as a Unicode text file if it either contains a non-Latin language or will be imported by a computer with a language setting that is different from your own computer.

Steps
1. Select the objects you want to export. 2. From the Project menu, click Languages, Export Translation File. 3. In the Project Languages box, click the languages you want to export, and click the arrow button to move them into the Languages to be exported box. You must export the design language of the model that will use the translation table. For example, if the translation table will be used in a model that uses French as the design language, you must export French. Framework Manager exports the appropriate locale code for each language you select. If you do not select all the languages to be translated, you must manually enter the language codes in the first row of each new language column in the translation table. 4. In the Model objects to be exported box, select whether you want to export all model objects, or export only preselected objects and their children. 5. Enter the location and name of the translation table. 6. Click OK.

Import a Translation Table

For information about translation tables and relational metadata, see (p. 109). You can add text property values for each language defined in your model by importing translated data from a file. The imported file must be a translation table that was used by translators to enter the required translated values. The translation table must contain the design language of the model that will use the translation table. The translation table can contain a subset of the languages defined for the project. Note: Because SAP BW Variables behave as custom properties, text strings, such as captions, are not automatically imported from the translation file. You must manually edit the model.xml file.

Steps
1. From the Project menu, click Languages, Import Translation File. 2. In the Project Languages box, click the languages in the translation table, and click the arrow buttons to move them to the Translate from and Translate into box. You must select the design language for this model.

User Guide 163

Chapter 5: Preparing SAP BW Metadata for Use in Reports 3. In the Apply translation to box, select whether you want to apply the translation to all model objects, or only to preselected objects and their children. 4. Enter the location and name of the translation file. 5. Click OK.

Example - Create a Multilingual Project for SAP BW Metadata

For an example about relational metadata, see (p. 110). You want to create a model that can be used by English, French, and German report authors.

Steps
1. Create a new project, using the go_data_warehouse sample, and import SAP BW metadata in English and German. 2. Add French as a supported language: From the Project menu, click Languages, Define Languages. Move French from the Available languages box to the Project languages box. Click OK. 3. Export all the languages and objects in the project to a comma-separated value file (.csv) named GOSLDW-ML.csv. From the Project menu, click Languages, Export Translation File. In the Project Languages box, Ctrl+click English, French, and German, and click the top arrow to move them to the Languages to be exported box. In the Export languages to this file box, enter the location of GOSLDW-ML.csv. 4. Open the GOSLDW-ML.csv file in Microsoft Excel, and translate the strings for French, the language that you are adding. Note that each column represents a given language, and the file contains only the text strings that exist in the model. 5. In Framework Manager, import the translated file: From the Project menu, click Languages, Import Translation File. In the Project Languages box, move French into the Translate into box. In the Import translation table from this file box, enter the location of GOSLDW-ML.csv.

Modifying the Properties of Query Items

For information about query items for relational metadata, see (p. 111). A query item is the smallest piece of the model that can be placed in a report. It represents a single instance of something, such as the date that a product was introduced. Presentation hierarchy levels, key figures, and attributes are imported as query items in Framework Manager. Only one hierarchy from a dimension should be used in a report. For SAP BW metadata, you can modify only text-based properties, such as the name or screen tip. Because reports can contain different query items from one or more objects in the model, query item properties control many aspects of the final report. When you create a model dimension or model query subject, the query items inherit the properties of the data source query items on which they are based. The properties for query items or measures include the following. Query item property Name Description Description The name of the query item or measure. A description of the query item or measure.

164

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports Query item property Last Changed Screen Tip Expression Description The date that the query item or measure was last changed. A description that can appear in the published package for the report authors. Used to create embedded calculations that provide report authors with calculated values that they regularly use. This property is for measures only. External Name Is Hidden The name that appears in the data source. Whether to hide or show the query item or measure in the published package. Even when Is Hidden is set to True and the query item or measure is invisible to report authors, it is always present in the published package because the query item or measure may be needed by other objects in the model. You do not see the query item or measure in the Package Publish wizard. For example, a calculation may make use of a hidden query item. Usage The intended use for the data represented by the query item. This property is for query items only. Format Currency How information appears in a report. Which currency is used. This property cannot be changed in the Property pane. Use the Format property to change the currency. Data Type The data type that was set in the data source. Because this property is set in the data source, it is read-only in Framework Manager. Precision The number of decimal places. Because this property is set in the data source, it is read-only in Framework Manager. Scale How many digits are represented in the scale. For example, you can show numbers in thousands so that 100,000 means 100,000,000. Because this property is set in the data source, it is read-only in Framework Manager. Size The size of the query item or measure. Because this property is set in the data source, it is read-only in Framework Manager. Is Nullable Whether the query item or measure can contain a null value. Because this property is set in the data source, it is read-only in Framework Manager.

User Guide 165

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Query item property Display Type

Description How the query item is shown. The column value can appear in the reporting application as a picture, as a link, or as a value. The default is value. This property is for query items only.

MIME Type

The format that the column value uses. For example, if Display Type is set to picture, MIME Type could be jpeg. This property is for query items only. Note: The MIME Type property is not used by SAP BW.

Prompt Info Regular Aggregate Semi-Aggregate

Prompt behavior. The type of aggregation that is associated with the query item, measure, or calculation in the published package. The value that is set in the data source. For relational metadata, the Semi-Aggregate property value is set to unsupported, and the property is read-only. For SAP BW metadata, the Semi-Aggregate property shows the value that is set in the data source, and the property is read-only.

Is Unsortable

Whether the values of this query item can be sorted. This property is for query items that contain large objects such as BLOBs.

You can rename a query item in the Calculation Definition dialog box. Renaming the query item updates references to this query item. For information about the Usage, Regular Aggregate, and Semi-Aggregate properties, see (p. 166) changing the currency symbol, see (p. 169) prompts, see (p. 170)

Modifying How Query Items Are Aggregated

For information about aggregation of relational query items, see (p. 113). You can change how some query items and measures are aggregated in reports. Framework Manager applies aggregation rules when report authors create a report that uses an aggregated query item or measure. When you import metadata, Framework Manager assigns values to the Usage, Regular Aggregate, and Semi-Aggregate properties for query items and measures depending on the type of object that the query item or measure is in. The Usage property sets the aggregation rules and also drives transformations, such as star schemas. The Regular Aggregate and Semi-Aggregate properties identify the type of aggregation that is associated with the query item or measure. Report authors can override the values you set. The types of objects that query items or measures can be in are dimensions query subjects calculations

166

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports You can change existing Usage and Regular Aggregate property values by either automatically regenerating the values of selected objects You then know that these values are appropriate for the type of data they represent. modifying the values in the Properties pane You can select additional aggregation values that are not available through importing, such as average and maximum. You must understand what the data represents to know which aggregation rule is required. For example, if you aggregate a part number, the only aggregate values that apply are count, count distinct, count non-zero, maximum, and minimum.

Rules for Setting Properties for Dimensions

Framework Manager uses the following rules to set the Usage, Regular Aggregate, and Semi-Aggregate properties. Object Regular dimension Usage property Attribute Regular Aggregate property Unsupported Automatic if it is a calculation Sum if it is not a calculation Count Unsupported Semi-Aggregate property Unsupported Unsupported

Measure in a measure Fact dimension Query item in a measure dimension Identifier

For multidimensional metadata, you cannot change these properties for data source dimensions.

Rules for Setting Properties for Calculations

The Regular Aggregate property for a calculation in SAP BW metadata is set to Automatic. To determine what automatic means, these rules apply. Calculation key items all other items Aggregation type unsupported calculated

Rules for Setting Properties for Model Query Subjects

For model query subjects, Framework Manager uses the settings for the object that the model query subject is based on. Note: If you change an aggregation value for SAP BW metadata, the aggregation cannot perform time-based queries because the aggregation rules are not applied.

Usage Property
The Usage property identifies the intended use for the data represented by each query item. During importing, the Usage property is set according to the type of data that the query items represent in the data source. You need to verify that this property is set correctly. For example, if you import a numeric column that participates in a relationship, the Usage property is set to identifier. You can change the property.

User Guide 167

Chapter 5: Preparing SAP BW Metadata for Use in Reports For SAP BW query items, the value of the Usage property depends on the type of dimensional item the query item is based on. Usage property value Identifier Fact Attribute SAP BW object

Description

hierarchy level Uniquely identifies characteristic values at a particular level in a hierarchy. key figure display attribute Represents a key figure that typically is numeric data. Date and time data are also supported. Represents a display attribute that is associated with a characteristic.

Regular Aggregate Property

The Regular Aggregate property identifies the type of aggregation for the query item or calculation when you publish it. The report author can either use this default setting to perform calculations on groups of data, or apply a different type of aggregation. For example, if the Regular Aggregate property value of the Quantity query item is sum, and the report author groups it by Product Name, the Quantity column in the report shows the total quantity of each product. The following aggregation types are supported for SAP BW data sources: automatic average average non-zero is supported only when it is set in the data source. You cannot change the property to average non-zero in Framework Manager. calculated count count distinct count non-zero is supported only when it is set in the data source. You cannot change the property to count non-zero in Framework Manager. maximum median minimum standard deviation sum variance

Rules to Determine the Automatic Aggregation Type

If the calculation is in an SAP BW object, these rules apply. Calculation key items all other items Aggregation type unsupported calculated

Semi-Aggregate Property
For SAP BW metadata, the Semi-Aggregate property shows the value that is set in the data source, and the property is read-only. If the value is set to unsupported in Framework Manager, the semi-aggregate behavior is ignored in the report authoring tools.

168

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Regenerate Usage and Aggregation Property Values

For information about regenerating values for relational query items, see (p. 117). Using Framework Manager to regenerate the values of the Usage and Regular Aggregate properties ensures that they reflect the transformation rules. It is useful to regenerate these values before you publish a package to ensure that these properties reflect modifications to your model. When generating aggregation values, Framework Manager assigns a value that is based on the Usage property value, and the type of model object it is. Usage property value Identifier Attribute Fact Regular Aggregate property value Count Unsupported Sum

Steps
1. 2. 3. 4. 5. 6. In the Project Viewer pane, click one or more dimensions or query subjects. In the Properties pane, click the Properties tab. Change the Usage property to unknown. Change the Regular Aggregate property to unsupported. From the Actions menu, click Determine Usage. From the Actions menu, click Determine Aggregation Rules.

Format Query Items

For information about formatting relational items, see (p. 117). You can specify how query item values appear in a report. Use the Format property to choose a format type, such as text, date, and currency. Each format type contains properties that further specify how the data appears. For example, you can assign the Currency format type to a numeric query item, and then use the No. of Decimal Places property in the Data Format dialog box to specify how many decimal places appear in reports. Some characters are language-sensitive and appear properly only when your locale supports the applicable font. For example, for Japanese currency symbols to appear correctly, your locale must be set to Japanese. You can define properties for several query items at the same time. However, if the query items have different format types, all properties that were previously specified are overridden and the default values from the data source are used. If the original format types of the selected query items are the same, all the properties for the selected query items are set identically. For example, to use the same decimal separator for two query items and to keep the number of decimals different, each query item must be changed individually. If both are selected and changed at the same time, all properties including the number of decimals are set identically for both query items.

Steps
1. In the Project Viewer pane, click the query item you want to format. 2. In the Properties tab of the Properties pane, click the Format property. 3. Set the format type to currency to ensure that currency formatting is applied to all types of reports. 4. In the Currency scope box, specify the type of currency. If you do not see the currency you want to use, click the Add button. 5. In the Properties box, select or type the appropriate property value. 6. Click OK. User Guide 169

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Define a Prompt Control

For information about prompt controls for relational metadata, see (p. 118). Prompts help users quickly find the information they need in a report. Prompts are generally defined in reports. However, you can change the definition of the dimension or query subject in the model so that a prompt appears automatically when report authors create filters. This is useful for query items, such as ProductTypeCode, whose values are not shown in a report but are useful for filtering data. In Framework Manager, prompt behavior is defined through a compound query item property named Prompt Info. The Prompt Info property contains the properties that affect how prompt controls are generated by Cognos 8.

Prompt Types
The Prompt Type property sets the type of prompt control that is generated when the report is run, such as an edit box or a pull-down list. Use this property to have the prompt show one query item but use a different one. For example, the prompt can show Employee Name but use Employee Number. The default value for this property is Server Determined. Value Prompt Control

Server Determined The type of prompt control is based on information in the server, such as the data type of the query item. Edit Box A simple text box. If the data type of the column is date or dateTime, this value generates a date or date-time control as well as the text box. A date control with a calendar interface. A date-time control with a calendar interface. For SAP BW metadata, this value is not relevant. A date-time interval control. For SAP BW metadata, this value is not relevant. A time control that filters data based on the selected time period. For example, if you define a Select Time prompt for Order Time, the user can use the time control to show all orders placed after 1:00, or all the orders placed between 10:00 and 11:00. If you are referring to a time member, you must use the exact values only. If you are using a range, the end points of the range must correspond to values in the data source. Select Value A drop-down list.

Select Date Select Date/Time Select Interval Select Time

Select with Search A list control so that users can search for values. For SAP BW metadata, this value is not relevant. Select with Tree A tree prompt control for prompts that are based on a hierarchy node.

Parent Item in a Cascading Prompt

The Cascade on Item Reference property indicates that the generated prompt is part of a series of generated cascading prompts. The query item that you reference in this property is the parent item in the cascade. The system prompts the user for the cascade item before prompting them for the current query item.

170

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports For example, if you want to prompt for Product Line and then Product within the selected line, set the Cascade On Item Reference property of the Product query item to Product Line.

Display Item to Show

The Display Item Reference property identifies the query item that the prompt shows if it is different from the query item whose properties you are editing. For example, if you want to prompt the user for Product Number but show the Product Name to the user, set the Display On Reference property of the Product Number query item to Product Name. This property is used only for data driven prompt controls whose Prompt Type properties are set to either Select Value or Select with Search.

Alternative Query Item for Filters

The Filter Item Reference property identifies an alternative query item that is used by any Report Studio or Query Studio filter. This property is used only when Report Studio or Query Studio generates a filter. This property helps create more efficient queries, because it is faster to filter on an indexed numeric column than a non-indexed string column. For example, if a report author wants to create a Product Name filter that uses the values in Product Number, you can set the Filter Item Reference property of Product Name to Product Number. You can also set the Display Item Reference property of the Product Number query item to Product Name, so that the user is prompted to select a name rather than a product number.

Steps
1. 2. 3. 4. Click the query item. In the Properties pane, click the Properties tab. Click the plus sign (+) next to the Prompt Info property. Modify the prompt properties to reflect the behavior you require.

Modify Multiple Objects at Once

For information about modifying relational objects, see (p. 119). You can modify a property for multiple objects at the same time. These objects can be dimensions, query subjects, or query items.

Steps
1. Select the objects that you want to modify. Only the properties that are common to all objects appear in the Properties pane. 2. If you want to sort the property values, double-click the property heading. An arrow appears to indicate the direction in which values are sorted. You can toggle between ascending and descending order. 3. If you want to filter property values, click the arrow to the right of the property heading, and then either select a value or click Custom to define the criteria for the rows that you want to show. 4. Make any changes to the values of the property.

Adding Business Rules

For information about business rules for relational metadata, see (p. 120). Business rules that were created in SAP BW are imported into Framework Manager. You can add more business rules to your model to refine the retrieved data and to ensure that the right information is available for report authors. You can add calculations so that report authors can include calculated data in their reports (p. 172)

User Guide 171

Chapter 5: Preparing SAP BW Metadata for Use in Reports create and apply filters so that you can limit the data that a query subject retrieves (p. 174) add prompts so that users are prompted to filter data when they open a report (p. 176) use session parameters (p. 184) and parameter maps (p. 183) to dynamically resolve expressions create a security filter to control the data that is shown to report authors when they set up their reports (p. 200)

Advantages
Creating business rules and storing them in the model instead of in reports has these advantages: They save time. You and your users do not have to re-create them every time they are needed. They ensure consistency. Your users all use the same definitions. For example, Low Margin means the same thing throughout the organization. They are easy to update. You can maintain the business rules centrally so that all reports are updated automatically as the rules evolve. For example, if the definition for Low Margin changes, all reports that use the Low Margin calculation are updated automatically. They enhance security. For example, you can use filters to limit the data that your users can see.

Create a Calculation
For information about calculations for relational metadata, see (p. 120). You can create calculations to provide report authors with calculated values that they regularly use. Calculations can use query items, parameters, variables, calculated members, expressions, and expression components, such as functions. Punctuation characters, such as the question mark (?), must be in 7-bit ASCII character code. If you type a punctuation character from a multi-byte enabled keyboard, ensure that you type the 7-bit ASCII representation of the character. For example, type Alt+063 for the question mark. Avoid using characters that are used for expression operators in the name of the calculation. Syntax errors may occur when the expression is evaluated. For example, a calculation named Margin * 10 causes errors when used in an expression such as [Margin * 10]< 20. At query time, Framework Manager returns a null value for any calculation that contains a divisor whose value is zero. Framework Manager cannot detect zero-division errors in functions such as average and mod, because the division operator is not explicit. Framework Manager supports two types of calculations: stand-alone and embedded.

Stand-alone Calculations
Use a stand-alone calculation when you want to reuse the expression. You can apply a stand-alone calculation to one or more dimensions or query subjects to provide calculated data to a report, or include it in a package to make it available to your users. By moving a stand-alone calculation or a shortcut to it into a folder, you can better organize your model objects.

Embedded Calculations
You may want to use a calculation with only one dimension or query subject. You can create an embedded calculation when modifying a relational data source query subject, model query subject, or dimension. If you start with an embedded calculation, you can later convert it into a stand-alone expression that you can apply to other dimensions or query subjects.

172

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports Tip: Right-click the calculation expression in the Calculations tab and click Convert to Stand-Alone Calculation.

Steps
1. Do one of the following: If you want to create a stand-alone calculation, click the model folder and, from the Actions menu, click Create, Calculation. If you want to create an embedded calculation, double-click the dimension or query subject that will contain the calculation, click the Calculations tab, and then click Add. 2. In the Name box, type a name for the calculation. 3. Define the expression. Goal Add items Add functions Add parameters Action On the Model tab, click a query item, filter, or calculation and click the arrow. On the Functions tab, choose a component and click the arrow. On the Parameters tab, click a parameter and click the arrow.

Limit test results Click the options button, select the Restrict the maximum number of rows to be returned check box, and type the required number of rows to be returned. Override session Click the options button, click Set, enter a value in the Override parameters Value field, and click OK.

Override prompt Click the options button, and then click Prompts. values The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model.

4. To test the calculation, click the test button. You can test only calculations that contain query items. If a calculation contains a function, for example _add_days, the test sample button is not available. 5. Click OK. 6. Modify the Data Type property to identify the type of data the calculation returns. The report authoring tool uses this information to format the data that the calculation returns.

Not Supported by SAP BW

SAP BW does not support all operators or summaries. This can be confusing if you have imported SAP BW metadata and non-SAP BW metadata into the same model. SAP BW does not support the following operators: contains ends with like lookup starts with SAP BW does not support the following member summaries: date-time

User Guide 173

Chapter 5: Preparing SAP BW Metadata for Use in Reports interval interval month interval day interval day to hour interval day to minute interval day to second interval hour interval hour to minute interval hour to second interval minute interval minute to second interval second interval year interval year to month time with time zone timestamp with time zone

Cell values are date, number, or time. Attribute values are strings. For information about functions, see "Using the Expression Editor" (p. 259) overriding session parameters, see (p. 184)

Create a Filter
For information about filters for relational metadata, see (p. 122). A filter is an expression that specifies the conditions that rows or instances must meet to be retrieved for the dimension, query subject, calculation, or report to which the filter is applied. A filter returns a boolean value so that you can limit the rows returned by a dimension or query subject. For example, you can use the in_range function to create a filter that retrieves data for products introduced in a specific time frame. The syntax for this example looks like this:
[gosales_goretailers].[Products].[Introduction date] in_range {Feb 14, 1999 : July 14, 2005}

Note: When using a date or time function, you must use a 24-hour clock. Framework Manager does not support "a.m." or "p.m." in expressions. For example, use 20:00 to signify 8 p.m. You can restrict the data represented by dimensions or query subjects in a project by creating a security filter. The security filter controls the data that your users can see when they set up their reports. You can also apply governors to restrict the data that the queries in a package retrieve. Framework Manager supports two types of filters: stand-alone and embedded.

Stand-alone Filters
Use a stand-alone filter when you want to reuse the expression. You can add a stand-alone filter to one or more dimensions or query subjects to limit the data that the query retrieves when the filtered dimension or query subject is used in a report, or you can include it in a package to make it available to your users. By moving a stand-alone filter or a shortcut to it into a folder, you can better organize your model objects.

Embedded Filters
You may want to use a filter with only one dimension or query subject. You can create an embedded filter when modifying a dimension, relational data source query subject, or model query subject.

174

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports If you start with an embedded filter, you can later convert it into a stand-alone expression that you can apply to other dimensions or query subjects. Tip: Right-click the filter expression in the Filters tab and click Convert to Stand-alone Filter.

Steps
1. Do one of the following: If you want to create a stand-alone filter, click the model folder and, from the Actions menu, click Create, Filter. If you want to create an embedded filter, double-click the dimension or query subject that will contain the filter, click the Filters tab, and then click Add. 2. In the Name box, type a name for the filter. 3. Define the expression. Goal Action

Add query items On the Model tab, drag the objects you want to the Expression and filters Definition box. Add functions On the Functions tab, drag the functions to the Expression Definition box.

Add parameters On the Parameters tab, drag the parameters to the Expression Definition box. Limit test results Click the options button, select the Restrict the maximum number of rows to be returned check box, and type the required number of rows to be returned. Override session Click the options button, click Set, enter a value in the Override Value parameters field, and click OK.

Override prompt values

Click the options button, and then click Prompts. The Model Prompts Manager dialog box appears, which shows all prompts, and their values, that are in the model.

4. To test the filter, click the test button. 5. Click OK. For information about security filters, see (p. 200) functions, see "Using the Expression Editor" (p. 259) parameters, see (p. 183) session parameters, see (p. 184) You can also apply governors to restrict the data that the queries in a package retrieve (p. 194).

Applying a Filter
For information about filters for relational metadata, see (p. 123). To apply a filter, you must modify the dimension, data source query subject, or model query subject. The query subject must either contain the query items that the filter references, or have a relationship path to the query subjects that contain the query items.

User Guide 175

Chapter 5: Preparing SAP BW Metadata for Use in Reports You can embed a stand-alone filter in dimensions or query subjects, but if you want a different usage for each embedded filter, you must create different versions of the stand-alone filter. Otherwise, your users could be required to fill in a prompt that you thought was optional if there is any instance where the usage is set to mandatory. For example, in query subject A, you define the embedded filter as optional. In query subject B, you define it as mandatory. When your users create a report that uses both query subjects, they are required to choose values in both filters, even the one defined as optional. All instances of the filter are considered to be mandatory when used in the same query. The solution is to create different versions of the filter, each with its own name. When you apply a filter, you specify how it is used by selecting one of the following usage values. Always Applies the filter whenever the dimension or query subject is run, regardless of whether the report contains the query item that is filtered. Always is the default usage value. Use this usage value to ensure specified data is filtered out of all reports. For example, your company may have obsolete information that it stores but does not want to report on. Design Mode Only Limits the amount of data that the report authors and modelers retrieve when designing. By limiting data retrieval, design-time results appear much more quickly. Optional Does not need to be applied. The user is prompted to filter data and can leave the filter blank. The report retrieves all data for the dimension or query subject. Applies only to filters that use the ? ? syntax.

Using Prompt Values to Filter Data

For information about prompt values for relational metadata, see (p. 125). You can substitute a prompt for a value so that users can filter data by typing a value when the report opens. In general, it is better to define type-in prompts in the reports to make use of additional prompt features in the reports. However, report authors cannot modify some variables. For these variables, you can use Framework Manager to define type-in prompts. You can use prompts in parameter maps session parameters expressions, such as filters and calculations The syntax for using a prompt as a value is
?<PromptName>?

When you test a model object that references a prompt, Framework Manager asks you to enter the prompt value. Framework Manager uses this value for either the duration of the session, or until you clear the prompt value. You can change the session value of prompt values through the Options dialog box. This dialog box is available when you modify a dimension or query subject, or define a calculation, filter, or query set. You can change the prompt value at the time that you are testing the expression that references that value. If you select the Always prompt for values when testing check box in the Prompt dialog box, Framework Manager prompts you for a value every time you test the object. When updating the object or performing a count, Framework Manager uses the existing prompt value, if one exists. You can also set up prompt properties for query items (p. 170).

176

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

SAP BW Variables
SAP BW variables are parameters of a BEx SAP BW Query that are set up during query definition. When you run the query, the SAP BW variables are filled with values. They function as placeholders and can be processed in different ways. They are automatically exposed as prompts at run time. SAP BW variable information is included in a composite custom property named SAP BW Variables that exists only if a data source has one or more variables associated with it. The SAP BW Variables property contains one or more composite properties, each of which must be assigned a unique name. Each property represents a description of a single SAP BW variable. Because the variable information is specified in a custom property, Framework Manager does not validate these properties. Framework Manager supports these types of SAP BW variables: characteristic There are two kinds of characteristic variables: characteristic value and hierarchy node. Characteristic values variables select characteristic values. Hierarchy node variables select values from any position in a presentation hierarchy. hierarchy The user is not prompted for a value because Cognos 8 automatically populates it at run time based on the selected hierarchy. formula The user types a numeric value at run time. Use formula variables if a formula component should be entered only when a query is run. For example, you can use a formula variable for a value-added tax rate to process the current rate at run time. authorization Authorization variables are like other variables, but Cognos 8 automatically populates the variable values with the users credentials. SAP BW uses these credentials to supply the information needed by an SAP BW Query that has security applied to it. Variables for hierarchies function as placeholders for the hierarchy of a characteristic. All the values for hierarchy variables are read-only. The SAP BW variable information is obtained using the SAP BW BAPI MDDataProviderBW::GetVariables.

Name Property
This property is a string value. SAP BW equivalent: VARIABLE_NAME Restrictions: Read-only.

Caption Property
The string value for this property is a composite and locale-dependent. Each locale in the model should be represented by a custom property whose value is the locale name. For example, if the locales en-ca and fr-fr exist in the model, define two custom properties named en-ca and fr-fr. The default value is obtained from SAP BW.

Default Low Caption and Default High Caption Properties

The value for each of these properties is a composite, locale-dependent string value. Each locale in the model should be represented by a custom property whose value is the locale name. For example, if the locales en-ca and fr-fr exist in the model, define two custom properties named en-ca and fr-fr. The default value is obtained from SAP BW. Restrictions: The Default High Caption property is applicable only for variables with a Selection Type of interval.

User Guide 177

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Fixed Value Property

This property is a boolean property that determines whether the value of the variable can be changed. If this property is set to true, report authors are not prompted for the associated variable, and the default value is always applied. The default value is false. Restrictions: This property is not applicable to hierarchy variables.

Selection Type Property

The possible values are value, interval, complex, multiValued. Value value interval complex multiValued Restrictions: Read-only. SAP BW Equivalent SAP_VAR_SEL_TYPE_VALUE SAP_VAR_SEL_TYPE_INTERVAL SAP_VAR_SEL_TYPE_COMPLEX SAP_VAR_SEL_TYPE_COMPLEX

Entry Type Property

The default value is obtained from SAP BW. Value optional mandatory mandatoryNotInitial SAP BW Equivalent SAP_VAR_INPUT_TYPE_OPTIONAL SAP_VAR_INPUT_TYPE_MANDATORY SAP_VAR_INPUT_TYPE_MANDATORY_N OT_INITIAL

Restrictions: Read-only.

Data Type
The default value is obtained from SAP BW. Value xsdString xsdDate SAP BW Equivalent CHAR CHAR The VAR_TYPE value is SAP_VAR_TYPE_MEMBER and the reference dimension is based on 0CALDAY. xsdFloat xsdDatetime xsdInt xsdLong FLTP DATS NUMC, DEC, INT1, INT2, or INT4 NUMC, DEC, INT1, INT2, or INT4

Restrictions: Read-only and hidden.

178

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Default Low Value and Default High Value Properties

Each of these properties specifies a range of values. The default value is obtained from SAP BW. Restrictions: The Default High Value property is applicable only for variables with a Selection Type of interval.

Description Property
This property is a string value.

SAP BW Variable Type Property

The possible values are numeric, characteristic, hierarchy, or hierarchicalNode. The default is obtained from SAP BW. Restrictions: Read-only.

Prompt Type Property

The default value depends on the type of the variable. If the value of this property is not one of the predefined values, it is assumed to be hierarchyPickList. Value typeIn pickList calendar hierarchyPickList notApplicable Restrictions Required for numeric variables and optional for characteristic values Optional for characteristic variables Only for characteristic variables based on 0CALDAY Optional for all presentation hierarchies Required for hierarchy variables

Restrictions: Read-only for some types of variables such as characteristic and formula.

Level Restriction Property

This property is a numeric value. The default value is 1. Restrictions: Applicable only for hierarchical node variables with a Prompt Type of hierarchyPickList.

Trim Levels Property

This property is a string value that reduces the number of members in a hierarchical picklist. If the property is set to zero (0), members from all levels of a hierarchy are included in the prompt. You can also specify a range such as 2:4 to include only the members from certain levels. If the starting and ending ranges are the same, such as 3:3, only members from that level will be included. The default value is zero (0). Restrictions: Applicable only for characteristic variables with a Prompt Type of hierarchyPickList.

Use Default Values Property

This property is a boolean property that determines whether the default values will be used. If this property is set to true, report authors are not prompted for the associated variable, and the default value is always applied. The default value is false.

User Guide 179

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Initial Number of Pick List Values Property

A numeric value that specifies the initial number of values used to populate a picklist, hierarchical picklist, or prompt. The default value is zero (0), which means all.

Maximum Number of Values Property

A numeric value that specifies the maximum number of values used to populate a picklist, hierarchical picklist, or prompt. This property is applied after the Trim Levels property. The default value is 100.

Font Type Property

This property is a string value. If you change the font type, Framework Manager does not check to ensure that you have entered the font type correctly. If there is an error, Framework Manager will use the font type set for the type of variable you are working with.

Dimension Property
This property is a string value. The default value is obtained from SAP BW. The SAP BW equivalent for this string value is REFERENCE_DIMENSION. Restrictions: Read-only and hidden. Not applicable for numeric variables.

Hierarchy Property
This property is a string value. The default value is obtained from SAP BW. The SAP BW equivalent for this string value is REFERENCE_HIERARCHY. Restrictions: Read-only and hidden. Applicable only for characteristic variables.

Default Values and Parameter Maps

The Default Low Value and Default High Value properties may contain expressions that use parameter maps. You can use parameter maps to define a value for a target currency variable based on the users locale. For example, you define a parameter map that provides an ISO currency code. The value for the Default Low Value property could be defined as
#$Currency_Map[runLocale}#

This parameter map is used when the SAP BW variable Target Currency is used in a report. These are the only properties related to SAP BW variables that can use parameter maps.

Numeric Variable Property Values

The following variable properties are applicable to numeric variables: Property Type Caption Selection Type Entry Type Data Type value Default value numeric

180

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Property Default Low Default High Prompt Type Fixed Value

Default value

typeIn false

You can change the default values for a numeric variable except for the Prompt Type property, which is read-only.

Hierarchy Variable Property Values

The following variable properties are applicable to hierarchy variables: Property Type Caption Selection Type Entry Type Data Type Default Low Default High Prompt Type not applicable value obtained from SAP BW xsdString Default value hierarchy

Because hierarchy variables are resolved entirely at run time, all these properties are read-only.

Characteristic Variable Property Values

There are two kinds of characteristic variables: characteristic value and hierarchy node. Characteristic values variables select characteristic values. Hierarchy node variables select values from any position in a presentation hierarchy.

Characteristic Value Variable Property Values

The following variable properties are applicable to characteristic value variables: Property Type Caption Selection Type Entry Type Data Type Default Low obtained from SAP BW obtained from SAP BW xsdString If the entry type is value or complex, the default property is shown. If the entry type is interval, the default low property is shown. This value is obtained from SAP BW. Default value characteristic

User Guide 181

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Property Default High

Default value If the entry type is value or complex, the default property is shown. If the entry type is interval, the default high property is shown. This value is obtained from SAP BW.

Prompt Type

typeIn or pickList This depends on the number of members in the referenced dimension. If the value is invalid, typeIn is used.

Fixed Value

false

A characteristic value variable for the 0CALDAY dimension is shown in the model as a date. The Data Type property is set to xsdDate and the Prompt Type property is set to calendar. The Prompt Type property is read-only for the 0CALDAY dimension.

Hierarchy Node Variable Property Values

The following variable properties are applicable to hierarchy node variables: Property Type Caption Selection Type Entry Type Data Type Dimension Hierarchy Default Low Default High Prompt Type Trim Levels Fixed Value Maximum Number of Values hierarchy PickList zero (0) false 100 value obtained from SAP BW xsdString obtained from SAP BW obtained from SAP BW Default value characteristic

You can change the Prompt Type property to typeIn or pickList.

Picklist Prompts
Each picklist prompt contains a pre-defined number of values. These values are determined by the Maximum Number of Values property. If the number of actual values is less than or equal to the default number of values, the prompt is generated as a single picklist prompt. If the number of actual values exceeds the default number, two prompts are generated in this order: a bound range parameter with a starting value of 1 and an ending value determined by the Maximum Number of Values property 182 Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports This parameter is of the type xsdUnsignedLong and is optional. The name of the parameter is the name of the original prompt followed by _range_prompt. The caption is locale-specific. If this is a multilingual model, you must store the template for the caption in a message file. a picklist prompt containing the default number of values

Create a Parameter Map

For information about parameter maps for relational metadata, see (p. 125). Use parameters to create conditional query subjects that allow for substitutions when the report is run. Parameter maps are objects that store key-value pairs. Parameter maps are similar to data source look-up tables. Each parameter map has two columns, one for the key and one for the value that the key represents. You can manually enter the keys and values, import them from a file, or base them on existing query items in the model. All parameter map keys must be unique so that Framework Manager can consistently retrieve the correct value. Do not place quotation marks around a parameter value. You can use quotation marks in the expression in which you use the parameter. The value of a parameter can be another parameter. However, you must enclose the entire value in number signs (#). The limit when nesting parameters as values is five levels. When you use a parameter map as an argument to a function, you must use a percentage sign (%) instead of a dollar sign ($). Note: If you are using SAP BW metadata, you cannot use a query item to generate the keys and values of a parameter map. For information about parameterized XML connection strings, see (p. 63).

Steps
1. 2. 3. 4. Click the Parameter Maps folder and, from the Actions menu, click Create, Parameter Map. In the Name box, type a name for the new parameter map. Click Manually enter the parameter keys, and/or import them from a file and click Next. Choose how to enter values: To manually enter values, click New Key, type a key, and press Tab to enter a value for that key. To import keys and values, click Import File and identify the location of the appropriate .csv file. You can import from a .txt file only if the values are separated by tabs rather than commas. Note: If you are going to use a parameter in a data source query subject, the value must use English-specific punctuation. This means that you must use a period (.) to represent a decimal and a comma (,) to separate lists of values. 5. Modify existing parameters as required. Goal Assign a default value Action In the Default Value box, type a value. If the key is used in an expression that is not mapped, the default value is used. Select a row and click Delete. Select the row you want to modify, click the Edit button, and type a value. Click Clear Map.

Remove a parameter Modify a parameter Clear all keys and values 6. Click Finish.

User Guide 183

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Create a Session Parameter

For information about session parameters for relational metadata, see (p. 128). A session parameter is a variable that Framework Manager associates with a session. For example, user ID and preferred language are both session parameters. Because session parameters are key and value pairs, you can think of each session parameter as an entry in a parameter map named Session Parameters. You use a session parameter in the same way that you use a parameter map entry, although the syntax for session parameters is slightly different. You can define additional parameters by using model session parameters. Each session parameter must have a name and a default value. You can define an override value to test the results that value returns. The override value is valid only when you have the model open, and is not saved when you save the model. If no override value exists, Framework Manager uses the default value when it executes a query that contains a session parameter. The rules governing the use of parameters include the following: All possible return values must have the same data type. Only one value can be defined. There are two types of session parameters: environment and model.

Environment Session Parameters

Environment session parameters are predefined and stored in Content Manager. By default, the following session parameters appear in Framework Manager: runLocale account.defaultName account.personalInfo.userName If you log on anonymously, you will see only runLocale and account.defaultName(Anonymous). If your authentication source supports other parameters and you entered information about them in the authentication source, you see other session parameters, such as account.personalInfo.email.

Model Session Parameters

If you need a session parameter that does not exist, you can create a model session parameter. Model session parameters are stored in a parameter map named _env. They are set in the project and can be published with a package. Model session parameters must have their values set within the scope of objects in the Framework Manager model. The scope can include the use of existing environment session parameters, as well as static values.

Steps
1. From the Project menu, click Session Parameters. 2. Click New Key and type a session parameter key and value. 3. Choose how to handle the override value. To avoid having to set the override value every time you edit the project, set the session parameter as a value. To avoid having to remove the project setting each time before you publish it, set the session parameter as a session override. 4. Modify existing parameters as required. Goal Change the parameter value Action Click the row that contains the value you want to change, click Edit, and type a value.

184

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Goal Assign a default value Remove a parameter Clear an override value 5. Click Finish.

Action In the Default Value box, type a value. Framework Manager uses the default value if a key has an invalid value. Click a row and click the Delete button. You cannot delete an environment session parameter. Click a row and click Clear Override.

Organizing the Model

For information about organizing a relational model, see (p. 136). When you organize the model, you make it easier for your users to find and understand the data in the model. You also make the model easier for you to manage and maintain. We recommend that you create several views, or layers, in the model: Keep the metadata from the data source in a separate namespace or folder. In Framework Manager, this is called the import view. Create one or more optional namespaces or folders for resolving complexities that affect querying using query subjects or dimensional objects. To use Analysis Studio or any OLAP-style queries, there must be a namespace or folder in the model that represents the metadata with dimensional objects. Create one or more namespaces or folders for the augmented business view of the metadata that contains shortcuts to dimensions or query subjects. In Framework Manager, these are called the business view. Use business concepts to model the business view. One model can contain many business views, each suited to a different user group. You publish the business views. Security can be defined in any of the views. It depends on your business requirements. For example, if you need to keep everyone from viewing an object, you add security to the object in the import view. Typically security is applied in the business view. You can include metadata in several folders by using shortcuts (p. 185) organize objects by creating namespaces or folders (p. 186) organize query subjects by creating query item folders (p. 186) organize measure dimensions by creating measure folders (p. 187)

Use Shortcuts
For information about shortcuts for SAP BW metadata, see (p. 140). A shortcut is a reference to an object, such as a relationship, a dimension, a query subject, or a folder. We recommend that you use shortcuts in the business view when there is an overlap between user groups and you want to include the metadata in more than one folder. With shortcuts, you can have multiple references to an object. For example, you create folders named Orders, Products, and Customers. If you want both Orders and Customers to contain the same dimension, you must create a shortcut to the dimension and add it to both folders. If there is more than one shortcut to the same object in the same folder or namespace, the shortcuts act as aliases. When you create a shortcut, Framework Manager does not set the Screen Tip and Description properties. Unless you define these properties, the values shown in the report authoring tools are the same as those defined in the object that the shortcut references. User Guide 185

Chapter 5: Preparing SAP BW Metadata for Use in Reports Tip: To go to the object that the shortcut references, right-click the shortcut and click Go To Target. For information about modifying properties, see "The Properties Pane" (p. 19).

Shortcuts and Dimensions

Shortcuts result in fewer dimensions to maintain. You can keep dimensions in the import view and keep shortcuts in the business view. When you create a shortcut to a dimension, you cannot customize which query items are in the shortcut. The entire dimension is included in the shortcut. If you have multiple star schemas, only one dimension must exist for a dimension table. All other instances of the dimension are shortcuts to the original. By using shortcuts, you can build queries involving multiple fact tables that are related through shared dimension tables. The security you specify for an object is passed to shortcuts that reference the secured object. If you have a shortcut to a secured object, only users with permission to see the secured object can see the shortcut in the published package.

Create a Folder or Namespace

For information about folders and namespaces for SAP BW metadata, see (p. 141). You can create folders to organize objects by subject or functional area. This makes it easier for you to locate metadata in projects that have many query subjects or dimensions. You can nest folders by creating new folders in an existing folder. Tip: When viewing metadata in the Diagram tab, you can expand or collapse folders. From the Diagram menu, click Collapse All or Expand All. When you want to reuse identical objects with the same name, create separate namespaces. If you set security on a folder and then move objects into the folder, confirm that exclusions are set correctly.

Steps
From the Actions menu, click Create, Folder. In the Name box, type a name for the new folder. Click Next. Choose whether to create shortcuts to the objects or actually move the objects: To create shortcuts that reference selected objects, click Create a shortcut for the selected items. Do not select all the objects in the namespace to avoid creating a recursive structure in the published package. To move selected objects to the folder, click Move the selected items to the new folder. When you move an object that participates in a relationship, the relationship may also move. 5. Select the objects you want to add to the folder. 6. Click Finish. For information about reusing identical objects with the same name, see "Use Separate Namespaces" (p. 28) setting security on a folder (p. 202) 1. 2. 3. 4.

Create a Query Item Folder

For information about query item folders for SAP BW metadata, see (p. 142). You can create query item folders to organize query subjects or dimensions that contain a large number of query items. A query item folder can contain only query items and query item folders.

186

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports

Steps
1. In the Project Viewer pane, click a query subject or dimension. 2. From the Actions menu, click Create, Query Item Folder. A new query item folder appears in the Project Viewer, under the query items that belong to that query subject or dimension. 3. Drag the query items that you want into the query item folder. You cannot add query items that do not exist in the parent query subject or dimension.

Create a Measure Folder

For information about measure folders for SAP BW metadata, see (p. 142). You can create measure folders to organize measure dimensions that contain a large number of query items. You can nest measure folders within other measure folders. You cannot create a measure folder from a measure shortcut.

Steps
1. In the Project Viewer pane, click a measure dimension. 2. From the Actions menu, click Create, Measure Folder. A new folder appears in the Project Viewer, under the measures that belong to that measure dimension. 3. Drag the query items that you want into the measure folder. You cannot add measures that do not exist in the parent measure dimension.

Optimizing SAP BW Performance

You can improve performance of SAP BW models and queries by adjusting settings in Framework Manager and in the reporting applications.

Dimension Settings
For each dimension, check the settings for the Balanced, Ragged, and Hierarchy Sort Order properties. By default, Cognos 8 uses settings that will not fail for the hierarchy type. For dimensions that represent SAP BW characteristics, the Balanced property is set to true and the Ragged property is set to false. For dimensions that represent presentation hierarchies, the Balanced property is set to false and the Ragged property is set to true. If the data is already sorted in the SAP BW environment, set the Hierarchy Sort Order property to ascending or descending to bypass additional processing at run time. For information about the types of hierarchies, see "Working with Dimensions" (p. 144) and "SAP BW Hierarchies" (p. 147).

Balanced Hierarchies
If a presentation hierarchy is balanced, then the Balanced property of its associated dimension should be set to true. By default, it is assigned a value of false for all presentation hierarchies. A hierarchy is balanced if all leaf characteristic values occur at the lowest level of the hierarchy. By setting this property to true as appropriate, the Cognos 8 server is able to generate more efficient MDX. You can define whether a dimension represents a balanced hierarchy by modifying the Balanced property of a dimension. The value that you set depends on the type of object that the dimension represents, and whether the hierarchy is balanced. When all paths are of the same depth, set the Balanced property to true, otherwise set it to false.

User Guide 187

Chapter 5: Preparing SAP BW Metadata for Use in Reports The default value for a dimension representing a presentation hierarchy is false. For a dimension that represents a characteristic without a presentation hierarchy, this property is read-only and is assigned a value of true. Dimension represents characteristic presentation hierarchy that is balanced presentation hierarchy that is unbalanced presentation hierarchy whose structure is unknown Balanced property value true true false false

If you assign a value of true to the Balanced property of an unbalanced hierarchy, queries that involve this dimension may return incorrect data. If you assign a value of false to the Balanced property of a balanced hierarchy, performance may be slower.

Ragged Hierarchies
You can define whether a dimension represents a ragged hierarchy by modifying the Ragged property of a dimension. The value that you set depends on the type of object that the dimension represents, and whether you know if the hierarchy is ragged. By setting the Ragged property to false as appropriate, the Cognos 8 server is able to generate more efficient MDX. If a presentation hierarchy is not ragged, set the Ragged property of its associated dimension to false. By default, set all presentation hierarchies to true. The default value for a dimension representing a presentation hierarchy is true. A dimension that represents a characteristic without a presentation hierarchy is read-only. Dimension represents characteristic presentation hierarchy that is not ragged presentation hierarchy that is ragged presentation hierarchy whose structure is unknown Ragged property value false false true true

If you assign a value of true to the Ragged property of an unragged hierarchy, queries that involve this dimension may return incorrect data. If you assign a value of false to the Ragged property of a ragged hierarchy, performance may be slower.

Unbalanced Hierarchies
An unbalanced hierarchy can also be ragged. In a ragged-unbalanced hierarchy, there are gaps in the levels and the levels descend to different depths.

Limitations with Ragged and Unbalanced Hierarchies and Aggregated Values

Ragged and unbalanced hierarchies can create gaps within individual paths of a hierarchy, as well as nodes at intermediate levels with no descendants at lower levels. If a report includes query items from a single dimension that are from consecutive or adjacent levels in a hierarchy, the fact values associated with the lower levels should always aggregate to the values associated with the higher levels of the dimension in the report.

188

Framework Manager

Chapter 5: Preparing SAP BW Metadata for Use in Reports However, if the query items are not from consecutive or adjacent levels, and the underlying SAP BW hierarchy is ragged or unbalanced, it is possible that the values of the higher levels may not reflect the aggregation of the fact values from the lower levels. The aggregated fact values associated with the higher levels reflect the aggregated values in the data source. This is typical behavior for OLAP data sources, but may be counterintuitive to those accustomed to reporting against relational data sources.

Hierarchy Sort Order

If the values of a characteristic are stored in SAP BW in a sorted order, ensure that the Hierarchy Sort Order property matches that order, either ascending or descending. By default, this property is assigned a value of none. If a range filter is applied to the query item representing the identifier for the characteristic, this property can direct the Cognos 8 server to generate more efficient MDX.

Outer Join Governor Setting

By default, the Outer Joins governor is set to deny. For Framework Manager models based on SAP BW data sources, the effect is to treat all joins as inner joins. If the governor is set to allow, all joins are treated as outer joins. The governor setting in the report authoring tools overrides the governor setting in Framework Manager. For multiple-cube queries, Framework Manager treats the Outer Joins governor as if it is set to deny. The governor setting of allow is ignored.

Data Source Settings

You can use SAP BW variables to reduce and filter the data underlying an SAP BW Query. If improperly configured, variable prompts that use either a picklist or hierarchical picklist can perform poorly. Use the following properties to control the performance of these types of variable prompts: Level Restriction Use this property to reduce the number of characteristic values that populate a hierarchical picklist. There is a limited number of levels of a hierarchy from which values are obtained. If the value is zero (0), which is the default, characteristic values from all levels of a hierarchy (if applicable to the type of prompt) are used to populate the picklist. Otherwise, the property specifies a colon-separated range of levels from which values are obtained (the root level is zero). For a ragged hierarchy, you must specify all levels that you may want to use even if some branches do not have that level. Initial Number of Picklist Values Use this property to limit the number of values that initially populate a picklist. The default is 100. It is then under the control of your users to choose the begin and end ranges of values that populate the picklist. If the value is set to zero (0), all values are used to populate the picklist. Use Default Value Use this property to set the variable to a single value. Your users are not prompted for the value of a variable and consequently, the Cognos 8 server is not required to populate a picklist with values. However, this removes any flexibility on the part of your users to affect the value of a variable. Prompt Type Use this property to specify the type of prompt. Changing a picklist or hierarchical picklist prompt to a type-in prompt can dramatically improve performance because it does not require the application server to populate a picklist with values. Unfortunately, it also requires your users to be able to accurately enter characteristic values.

User Guide 189

Chapter 5: Preparing SAP BW Metadata for Use in Reports For information about other variables, see (p. 177).

Settings in the Report Authoring Tools

There are a few settings you can adjust in the report authoring tools to improve the performance of queries: outer joins A report author may choose to change the value of the Outer Join Allowed property for a query to determine how joins are interpreted by the Cognos 8 server. This property applies to a single query. The governor setting in the report authoring tools overrides the governor setting in Framework Manager. If there are no facts in the query and the Outer Joins governor as if it is set to deny, the report will use the default measure. For multiple-cube queries, Framework Manager treats the Outer Joins governor as if it is set to deny. The governor setting of allow is ignored. aggregation Reports containing aggregations and summaries run more efficiently if the aggregation applied to a query item matches the aggregation rule for the underlying key figure on the SAP BW server. In Report Studio, the easiest way of accomplishing this is to change the value of the Aggregate Function property to automatic. filter expressions Filters applied to member unique name or identifier query items are faster than filters applied to attribute query items. It is easier for report authors if the model distinguishes between the two types of query items.

190

Framework Manager

Chapter 6: Making Metadata Available to Report Authors

A package is a subset of the query subjects and other objects defined in the project. You then publish the package to the server so that the report authors can use the metadata. You can create several packages from the same project, with each package meeting different reporting requirements. Before you publish a package, you must create (p. 24) or open a project (p. 25) in Framework Manager and import metadata into the project (p. 28). You might also want to refine the project for reporting (p. 73) by creating and modifying the objects in the project. To publish a project: Check the project to ensure that the contents are consistent and do not contain any errors (p. 191). Set governors for reports (p. 194).

Create custom packages to suit different reporting requirements (p. 197). Add security to the package (p. 199). Analyze the effect of any changes you made to a package on the reports that were created
using the published packages (p. 208).

Specify languages in the package (p. 204). Publish the package to a location that report authors can access (p. 207).

Verify a Model
At any point in the modeling process, you can check the validity of your project. Before you publish a package (p. 207), you can also ensure that there are no invalid objects that can break queries in the published package. When you verify a model, Framework Manager detects various problems, such as invalid objects and their status. You can direct Framework Manager to repair the problems. The repair actions are applied to the model in the following order: fix invalid objects fix broken references fix invalid relationships fix aggregation rules add missing locales reset unsupported prompt types infer roles repair upgraded models re-evaluate To verify your model, see "Steps to Verify a Model" (p. 193).

Invalid Object Definition

Framework Manager warns you when your changes to an object mean it cannot execute. If you proceed, these are marked as invalid. When you verify a project, Framework Manager identifies any query subjects, shortcuts, filters, calculations, and relationships that were previously marked as invalid so that you can repair them.

User Guide 191

Chapter 6: Making Metadata Available to Report Authors The Verify dialog box may contain messages like this one: This object has a status of invalid. Unable to test the object.

Invalid References
Invalid references exist when an object, such as a shortcut, references another object to which it does not have access or which no longer exists in the project. The Verify dialog box may contain messages like this one: The property "property name" has a shortcut that references the shortcut "shortcut name" with the value "property value". Either the reference to the shortcut is not valid or the shortcuts reference to the target object is not valid. This property must reference an existing object.

Invalid Relationships
Framework Manager identifies query subjects and dimensions whose relationships are invalid. Invalid relationships include orphaned query subjects (query subjects with no relationships) multiple relationships (or relationship shortcuts) between query subjects (or query subject shortcuts) orphaned dimensions (packages that include regular and measure dimensions that are not associated by a scope relationship) The Verify dialog box may contain messages like these: This query subject is an orphan because it is not referenced by a relationship or relationship shortcut. The package contains orphan dimensions that are not in scope with other measure or regular dimensions.

Invalid Aggregation Rules

Framework Manager identifies any aggregate settings that are invalid for the data type of the query items to which they are applied. For example, if Product_Name has a character data type, its aggregate property cannot be set to either sum, count, or average. To repair the error, Framework Manager resets the aggregate property to unsupported. The Verify dialog box may contain messages like this one. This query item has the datatype "data type name" and has the regular aggregate rule "aggregation Rule name", which is not supported for this datatype.

Missing Locales
The default locale is assigned to any model objects which are missing locale based values. Review these to ensure that the locale assigned to the model objects are updated accordingly. The Verify dialog box may contain messages like this one. The object is missing the following locales "locale name". The repair action will add the missing locales to all multilingual properties.

Unsupported Prompts
When the usage property on a query item is set to fact but the value for the corresponding Prompt Type property is not Server Determined, the value is reset to Server Determined. For more information about prompt types, see "Define a Prompt Control" (p. 118).

Inferred Roles
If a level contains is missing the caption or business key roles, the values are assigned to the query item referenced by the key of a determinant of an underlying query subject. The Verify dialog box may contain messages like this one: None of the query items in this level have a role of Caption (or Business Key) specified. At least one query item must have this role specified, as it will be used to display the members in Cognos 8. 192 Framework Manager

Chapter 6: Making Metadata Available to Report Authors

Repairing Upgraded Models

Verifying a model immediately after upgrading performs the same checks that it would perform if the model had not recently been upgraded. You may receive some of the following messages after verifying recently upgraded models: The governor for enhanced model portability has been turned on which affects performance. All data types in the model will be ignored. There is no repair option for this. This governor forces the data type information to be refreshed for all query subjects whose status is set to Needs Re-evaluation. After the model has been verified and reported problems are resolved, you must manually set the governor back to its default state of False (p. 194). The object has a status of Needs Re-evaluation. Unable to validate this object. Repairing this problem refreshes the data type information of all DB query subjects that have a status set to Needs Re-evaluation, as well as validate the query and set the status to valid. This object contains deprecated dimensional information. Query subjects that have obsolete level or hierarchy properties are flagged as warnings. Repairing this problem allows you to choose whether you want to convert the query subjects to dimensions or to set the determinant property. The dimensional structure or determinants will be generated based on the old hierarchy and level properties. This object contains deprecated key and index information. Query subjects that continue to have key and index properties are flagged as warnings. Repairing this problem converts the key and index properties to determinants.

Re-Evaluate
The status for query subjects containing data type information has been set to needs reevaluation. When the query subjects are re-evaluated, the queries are prepared and tested. When the data type information is confirmed, the status for these query subjects returns to valid.

Steps to Verify a Model

1. From the Project menu, click Verify Model. Tips: To verify only a few objects, select the objects and click Verify Selected Objects on the Tools menu. After you verify the model, you can print the list of messages. Click View All Messages and then click Print. 2. Select the check box for each object you want to correct and click Repair. Tip: Choosing an object with multiple errors also selects all the errors for that object. 3. In the Repair Broken References dialog box, select which references you want to see: To show every reference that exists for the selected object, click Show all references. Use this option to view more context about how an object is used in valid relationships. To show only the references that are broken for this object, click Show only broken references. 4. Click the Retarget to/Delete column, and choose how to fix the broken reference: To locate the object you want to reference, click Browse. Tip: To use a reference that you have assigned to another object during this repair session, click the name of the reference. To delete the object that contains the broken reference, click Delete Object. Tip: You can resize the columns to see the complete object name. 5. Click the Apply to column and choose where you want to apply the reference: To apply the change to this object only, click This Reference Only. To apply the change to every object that references the same object, click Entire Project. 6. Click OK. A dialog box shows the number of objects that were repaired. A second dialog box shows the number of objects containing dimension information.

User Guide 193

Chapter 6: Making Metadata Available to Report Authors 7. Click Yes to repair the query subjects. 8. Select the method to repair query subjects and click OK. A dialog box shows the number of objects that were repaired. 9. Click OK. The upgrade procedure re-evaluates the query subjects and completes the upgrade procedure. After fixing invalid relationships, if the relationships still appear as broken in the Verify dialog box, close and re-open the model. When you repair a filter that contains an invalid reference, you must check its expression to ensure that the query items it now references do not contain invalid references. In the Expression Editor, any expression components that are invalid are underlined in red. For more information, see "Using the Expression Editor" (p. 259)

Set Governors
Use governors to reduce system resource requirements and improve performance. You set governors before you create packages to ensure the metadata in the package contains the specified limits. All packages that are subsequently published will use the new settings. There are a number of governors that you can set. Governor settings in the model can be overridden by governor settings in Report Studio.

Report Table Limits

You can control the number of tables that a user can retrieve in a query or report. Tables are counted as they are retrieved. When the query or report is run interactively and it exceeds the limit set for the number of tables, an error message appears and the data is truncated. When running in batch and the limit is exceeded, an error message appears and the query or report is shown with no tables. A setting of zero (0) means no limit is set.

Data Retrieval Limits

You can control the number of rows that are returned in a query or report. Rows are counted as they are retrieved. When you run a report and the data retrieval limit is exceeded, an error message appears and the query or report is shown with no data. You can also use this governor to set limits to the data retrieved in a query subject test or the report design mode. A setting of zero (0) means no limit is set. If you externalize a query subject (p. 205), this setting is ignored when you publish the model.

Query Execution Time Limits

You can limit the time that a query can take. An error message appears when the preset number of seconds is reached. A setting of zero (0) means no limit is set.

Large Text Items Limit

You can control the character length of BLOBS (binary large objects) that a user can retrieve in a query or report. When the character length of the BLOB exceeds the set limit, an error message appears and the query or report is shown with no data. A setting of zero (0) means no limit is set.

Allow Enhanced Model Portability at Run Time

You can use a separate but structurally similar data source at run time. The database schema must be the same between the two data sources.

194

Framework Manager

Chapter 6: Making Metadata Available to Report Authors This governor is selected upon initial upgrade. It prevents rigid enforcement of data types so that a Cognos 8 model can function as a ReportNet 1.x model until you update the data types in the metadata. It ensures consistent behavior with ReportNet 1.x by deriving a form of dimensional information from the relationships, key and index information in the data source. By default, the model is not portable at run time. If you select this governor, Cognos 8 retrieves metadata from the data source and caches it instead of using the metadata already cached in the model. If you do not use this governor, you must ensure that the following metadata are the same in the original and new data sources: collation sequence name collation level character set nullability precision scale column length data type

Allow Dynamic Generation of Dimension Information

Select this governor upon initial upgrade of a ReportNet 1.x model. This governor allows consistent behavior with ReportNet 1.x by deriving a form of dimension information from the relationships, key information, and index information in the data source.

Allow Usage of Local Cache

Select this governor to specify that all reports based on this model should use cached data. By default, this governor is disabled. After the governor is turned on, the model must be republished for the changes to take affect. This setting affects all reports that use this model. If you want a report to use a different setting than the model, you can do this in Report Studio. For more information, see "Improving Performance by Reusing Cached Data When Running a Report" (p. 196).

Outer Joins
You can control whether outer joins can be used in your query or report. An outer join retrieves all rows in one table, even if there is no matching row in another table. This type of join can produce very large, resource-intensive queries and reports. By default, governors are set to deny outer joins. As a result, outer joins are not automatically generated when, for example, you test a query item in Framework Manager. SQL is generated automatically when you run a report test a query item or relationship in Framework Manager create a new model query subject based on other objects (p. 95) If you keep the setting as deny, you are notified only if you create a relationship in the Diagram tab that includes outer joins. You are not notified if you create a relationship in a data source query subject that includes outer joins. If you set the governor to allow, dimension to fact relationships are changed from inner joins to outer joins. The outer joins governor does not apply in these circumstances: SQL that is generated by other means. If you set this governor to deny, it does not apply to the permanent SQL found in a data source query subject, whether the SQL was generated on import (p. 28), manually entered, or based on existing objects (p. 89). Framework Manager needs to generate an outer join to create a stitched query. A stitched query is a query that locally combines the results of two or more sub-queries by using a locally processed outer join.

User Guide 195

Chapter 6: Making Metadata Available to Report Authors Note: For SAP BW metadata, set this governor to generate all relationships as outer joins. Queries can then be very large because null values are not filtered out.

Cross-Product Joins
You can control whether cross-product joins can be used in your query or report. A cross-product join retrieves data from tables without joins. This type of join can take a long time to retrieve data.

Use With Clause When Generating SQL

You can choose to use the With clause with Cognos SQL if your data source supports the With clause. The With clause will be turned on for models created in Cognos 8. For upgraded models, it is turned off unless it was explicitly turned on in the ReportNet model prior to upgrading.

Steps
1. From the Project menu, click Edit Governors. 2. Specify the limits that you want to use when retrieving data. 3. Click OK.

Improving Performance by Reusing Cached Data When Running a Report

When you run a report, the query request is sent to the database and the result set is returned. After the initial report execution, you may decide to make changes to the report. Often, the report can be created without querying the database again. To take advantage of this, you should turn the query reuse feature on. When query reuse is turned on and you run a report for the first time, the query is stored in the cache of your current session and reused the next time you run the report. The queries are kept in the cache for each user. The cache is cleared when the report consumer exits the reporting tool and returns to the portal or when the report server times out the session, typically after five minutes of inactivity. The first time the report is run and the cache is created, the response time may be slightly negatively impacted. The performance improvement is realized by the report consumer on each subsequent report execution, when the response time is improved by as much as 80%. This performance improvement occurs because the report does not have to re-query the database. In addition to this, reduced queries to the database yields improved overall system performance, which positively impacts all users. Query reuse can be set on the model or on individual reports. To specify that all reports using a particular model should use cached data, enable the Allow Usage of Local Cache governor on the model in Framework Manager and republish the model. By default, this setting affects all reports that use this model.

Query Reuse in Cognos Viewer

If you want a report to use a different setting than the model, you can do this in Report Studio. In the Properties pane, change the Use Local Cache property. Set the property to No if you want to always execute the query. Set the property to Yes if you want to use cached results. If you want the report to use the same setting as the model, change the setting to Default. Changing the Use Local Cache property for one report does not affect other reports.

Reusing Cached Data in Query Studio

Query Studio reuses cached data under various conditions. If query reuse is turned on in the model and the action can be satisfied by a subset of the cached data set, the report uses the cached data. For example, changes to the report such as adding a filter or removing a column, may change the report data but the request can still be satisfied from a subset of the cached data.

196

Framework Manager

Chapter 6: Making Metadata Available to Report Authors If query reuse is turned off and the action can be satisfied from the cached data set without modifications, the report still uses the cached data. For example, changing the report format uses the previous data set even if query reuse is turned off. This is known as cursor reuse. Cursor reuse is used when the cached data can satisfy the request without modifications. Reports that were authored in Query Studio always use the same setting as what is specified in the model. If the model has query reuse turned on, the report attempts to use the cached data.

Deciding Whether to Use Query Reuse in Your Environment

Before deciding whether or not to turn query reuse on, consider the following: If most report consumers run reports interactively but run them only once, you may not experience a high level of performance improvement by caching data. Note: Regardless of the query reuse settings, reports that run in batch mode do not cache data. The size of the cache may impact Cognos 8 scalability. For example, if a report has a large result set, the cache will also be large. This should be taken into account when sizing and configuring your server environment.

Create or Modify a Package

You create a package to make metadata available to report authors. A package is a subset of a project. It must contain all the information that a specific user or group of users needs to create reports. A package contains query subjects whose SQL defines the query items and relationships that the package retrieves. When you create a package, you select the objects that a user will want to report on. When you create or modify a package, you can also apply security to the package (p. 199). For example, if your data source contains information from different areas of a business, you might decide to create different packages for Human Resources and Finance. Ensure that your package meets a broad but related reporting need. Each report can contain information from a single package only. After a package is published to the server, it is available for use by report authors.

Reusing Packages
You reuse packages by creating nested packages. When you create nested packages, you create a master package that is based on other existing packages. Using nested packages saves you time, and they are easier to maintain. Another advantage of using a nested package is that you publish only the master package. For example, you create three separate packages named Canada, Mexico, and the United States. Each package contains the project objects and security appropriate for that package. You can create one master North America package and include the packages Canada, Mexico, and the United States. When you need to publish the package for report authors, you publish only the North America package.

Select, Hide, Unselect

When you create a package, you can choose whether objects in a project can be selected based on the requirements of reports authors. Option Select Description The object can be used in reports and can be selected by report authors.

User Guide 197

Chapter 6: Making Metadata Available to Report Authors

Option Hide

Description The data within the object cannot be used in reports as it cannot be selected by report authors. Any existing reports referencing this object will not execute. For example, you include a model query subject in a package. Because model query subjects are dependent on data source query subjects (p. 89), you must add the data source query subject to your package. If you do not want report authors to see the data source query subject, you hide it.

Unselect

The object is not published. It cannot be used for reports and cannot be selected by report authors.

For example, package A has the query subject Country hidden and package B has the query subject Country selected. If package C includes package A and package B, then Country is included. However, if package C includes package A and package B, and you override the query subject Country in package C so that it is unselected, then Country is unselected.

Including a Model Query Subject in a Package

If a model query subject references other query subjects in macros or prompts, ensure that you include the referenced query subjects in the package. This can occur in the following situations: A macro for the model query subject references query items in another query subject. Another query subject is referenced in the Prompt Info properties.

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. 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. Tip: If you created other packages, we suggest that you add package references by clicking Using existing packages. 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. 5. Specify who has access to the package, and click Next. You can add users, groups, or roles (p. 199). 6. Move the language to be included in the package to the Selected Languages box, and click Next. 7. 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. For more information, see "Select Function Sets" (p. 69). 8. Click Finish and choose whether to publish the package (p. 207).

Steps to Modify a Package

1. Right-click the package you want to modify, and then click Edit Definition. 2. Click the objects you want to add to or remove from the package. Tip: To toggle through the options for an object, click the object icon, or select an option from the list. For more information, see "Select, Hide, Unselect" (p. 197). 3. Click OK. 4. If you want to add or remove package references to the package you are modifying, click Edit. 5. Click OK.

198

Framework Manager

Chapter 6: Making Metadata Available to Report Authors

Controlling Access to Metadata and Data

In Framework Manager, security is a way of restricting access to metadata and data across Cognos 8 products. There are different types of security in Framework Manager: data security (p. 200) You create a security filter and apply it to a specific query subject. The filter controls the data that is shown to report authors when they set up their reports. object security (p. 202) You secure an object directly by allowing users access to the object, denying users access to the object, or keeping it hidden for all users. package security (p. 203) You apply security to a package and identify who has access to that package. Each type of security uses users, groups, and roles to define access. There are business reasons for restricting access to data. For example, you may have data that contains confidential data, and only specific users are allowed to see it. You may have a variety of data, and your users only need to retrieve data from specific tables or columns. Or, you may have a table that contains many records, and your users only need to retrieve a subset of records from that table. If you are using SAP BW metadata, there can be underlying SAP BW security that affects your users access to level members. Therefore, assigning a user access to a level does not guarantee that the user also has access to the members in that level. For more information, see "Import from an SAP BW Data Source" (p. 30). Before you add security in Framework Manager, ensure that security was set up correctly in Cognos 8. For more information, see the Administration and Security Guide.

Add a User, Group, or Role

Users and groups are created for authentication and authorization purposes. You can use users and groups created in third-party authentication providers, as well as create your own in Cognos 8. In Framework Manager, you add data security (p. 200) and metadata security (p. 203) using these users, groups, and Cognos groups. For more information about security, see the Administration and Security Guide.

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 users in Cognos 8. Information about users, such as first and last names, passwords, IDs, locales, and e-mail addresses, is stored in the providers. Users can become members of groups defined in third-party authentication providers and groups defined in Cognos 8. A user can belong to one or more groups. If users are members of more than one group, their access permissions are merged.

Groups and Roles

Examples of groups are Employees, Developers, or Sales Personnel. Members of groups can be users and other groups. Group membership is part of the users basic identity. 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. A role is a special group. It represents a collection of users that have similar responsibilities and similar privileges in the organization. Members of roles can be users, groups, and other roles. Role membership is not part of the users basic identity. You can use groups created by your organization in third-party authentication providers, or create new groups in the Cognos namespace.

User Guide 199

Chapter 6: Making Metadata Available to Report Authors You create Cognos groups when you cannot create groups in your authentication provider groups are required that span multiple namespaces portable groups are required that can be deployed 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

Steps to Create a New Group or Role

1. 2. 3. 4. Right-click the package you want, and click Edit Package Access. Click New. Follow the instructions in the New Group wizard. Click Finish, and then click OK.

Steps to Remove a Group or Role

1. Right-click the package you want, and click Edit Package Access. 2. Click the user, group, or role you want to remove, and click Remove. 3. Click OK. When you remove Cognos groups or roles, you do not delete them from the third-party authentication provider or Cognos 8.

Steps to Add a Group or Role

1. Right-click the package you want to modify, and click Edit Package Access. 2. Click Add. Tip: To view all the users in a group, select the Show users in the list check box, and click the group you want. 3. Specify the users or groups. To add entries by selecting the names from the list, on the Navigate tab, select the check box next to the appropriate user, group, or role, and then click Add. To search for users, groups, or roles in a namespace you are currently using, on the Search tab, type the search criteria, and click Search. When the entry appears in the Search results box, select it and click Add. To add entries by typing the names, on the Type tab, in the Type the names text box, type the names of users, groups, and roles, in the following format, and then click Add. namespace_name;namespace_name/group_name;namespace_name/user_name For example, you add a Report Authors group and a user named scarter by typing the following LDAP;Cognos/Report Authors;LDAP/scarter. Separate each entry using a semicolon (;). The entries that you add appear in the Entries to be added box. Tip: Select all or Deselect all applies to the current page, which may not represent all available entries. 4. Click OK twice.

Add Data Security

You can restrict the data represented by query subjects in a project by creating a security filter. The security filter controls the data that is shown to the report authors when they set up their reports. For example, your Sales team consists of a Sales Director, and four Sales Managers. You create a security filter that includes the groups directors and sales managers, and apply the filter to the salary query subject. When the package is available for report authors, and a report is generated for the Sales Managers and the Sales Director, only the Sales Director can see the salary information for the sales managers. You can base the security filter on existing security filters. If you choose this option, the security filter inherits the filter, and all the filter properties. 200 Framework Manager

Chapter 6: Making Metadata Available to Report Authors When you create a security filter, you can also use existing project filters, or create new filters using the Expression Editor. For more information, see "Create a Filter" (p. 122). For more information about groups, see "Add a User, Group, or Role" (p. 199).

Steps
1. Right-click the query subject you want, and click Specify Data Security. 2. To add new users, groups, or roles, click the Add Groups button. For more information, see "Add a User, Group, or Role" (p. 199). 3. If you want to base the group on an existing group, click a group in the Based On column. Tip: If you do not see the group you want in the list, you must add the group to the security filter. 4. If you want to add a filter to a group, in the Filter column, click either Create/Edit Embedded Filter or Insert from Model. 5. Click OK.

Using the CSVIdentityName Macro Function

If you want row-level security based on UserClass values stored in your data source, implement a parameter map that maps the values in the data source to the corresponding roles and groups based on the user you are logged on as. You do this by using a parameter map as an argument with the CSVIdentityName macro function. This macro function retrieves account, group, and role information for the current user. It returns a string of comma-separated values from the parameter map in single quotation marks, such as 'clerks', 'technicians', and 'typists'. The CSVIdentityName macro function is used as a key in the specified map. You can use the list that is returned to build partial In clauses or to filter data based on the identity name of the current user. For example, you have user classes whose names do not correspond to the Roles_Groups parameter map: Key (Role or Group) Everyone Authors System Administrators Query Users NTLM You have this query subject:
(Security_column, value 1, value 2, value 3)

Value (User Classes) Group1 Group2 Group3 Group2 Group2

When you add a filter to the query subject, the filter uses a macro to look up a list of values like this:
Security_column in (#CSVIdentityName(%Roles_Groups)#)

For users in the Everyone, Authors, and System Administrators roles, testing shows this as:
Security_column in ('Group1','Group2','Group3')

Using the CSVIdentityNameList Macro Function

If security data in the data source is identical to the roles and groups defined in Cognos 8, you can use the CSVIdentityNameList macro function. The macro function optionally accepts a list separator as a parameter and then returns a separator delimited list that can be used in a filter with the In operator. You do not need a parameter map. Here is an example: User Guide 201

Chapter 6: Making Metadata Available to Report Authors

Security_column in (#CSVIdentityNameList()#)

For users in the Everyone, Authors, and System Administrators roles, testing shows this as:
Security_column in ('Everyone','Authors','System Administrators')

There are some considerations to keep in mind: users can belong to several groups or roles there is no way to distinguish between groups and roles so you must not reuse names for groups and roles this function works only in a filter and always returns 0..n values.

Add or Remove Object Security

Metadata security can be applied directly to objects in a project. When you add object-based security, you apply a specific user, group, or role (p. 199) directly to the object. You choose to make the object visible to selected users or groups. If you do not set object-based security, all objects in your project are visible to everyone who has access to the package. When you apply security to one object, all objects in the model will also have security applied to them. They will not be visible to anyone. Once you set security for one object, you need to set it for all objects. You can do this by setting security on the root namespace. You may want an object to be visible to only selected users, groups, or roles. For example, in your project, you may have a Salary query subject. You can make the Salary query subject visible to the Managers group, and keep it hidden from everyone else. If a user is a member of multiple user groups and an object is visible to one user group and denied to the other, the user will not have access to the object. For example, Jane belongs to two user groups: Sales and Marketing. The Sales group has access to the Products and Sales query subjects, and denied access to the Sales Forecast query subject. The Marketing group has access to Products, Sales, and Sales Forecast query subjects. Jane does not have access to Sales Forecast. When you secure an object, a package is automatically created in Framework Manager. The package name consists of an underscore (_) and the name of the secured object. These object-based packages are visible in the Explorer. You can use this package to see which objects in the project are included, hidden, or excluded from a specific user group. Every time you include that object in a package, and publish it for report authors, the same security rules apply for that object. When you publish a package that contains secured objects, the visible objects for users are the intersection of the package definition and the object security settings. If object-based security is not used, security applied to a package remains unchanged.

Scope of Object Security

The security you specify for an object is passed to shortcuts that reference the secured object. If you have a shortcut to a secured object, only users with permission to see the secured object are able to see the shortcut in the published package. If a model query subject, calculation, or filter references a secured object, the objects security is not passed to the model query subject, calculation, or filter. When you create a package containing the shortcut, the secured object does not need to be included in the package. For example, only sales managers are allowed to see the Sales Target query subject. You create a shortcut to Sales Target. When you package the model, you include the shortcut but not the Sales Target query subject. Sales managers are the only ones able to see the shortcut in the published package.

Tips
To see a list of the object-based packages, double-click the Packages folder. The list appears in the Explorer tab. To see which objects are secured against that specific object-based package, right-click the package, and click Explore Packages (p. 204). To determine if object-based security is set in the model, right-click the package, and click Explore Packages. Click the Roles Explorer tab. If object-based security was set, you see a package for the Everyone role.

202

Framework Manager

Chapter 6: Making Metadata Available to Report Authors To determine which objects are explicitly secured in the model, look at the objects icon in the Project Viewer. The top left corner of the icon is marked with an overlay. To find all objects that were explicitly secured under a given object, select the object and, from the Tools menu, click Find All Secured Objects. To remove object-based security for a particular user, group, or role, delete the package for that user, group, or role from the Project Viewer. To completely remove object-based security from the model, delete the package for the Everyone role from the Project Viewer.

Steps to Add Object-Based Security

1. Right-click the object you want to secure, and click Specify Object Security. Tip: You can select more than one object and then right-click them. 2. Select the users, groups, or roles you want to change. Or, click the Add button to add new users, groups, or roles. For more information, see "Add a User, Group, or Role" (p. 199). 3. Specify security rights for each user, group, or role by doing one of the following: To deny access to a user, group, or role, select the Deny check box next to the name for the user, group, or role. Deny takes precedence over Allow. To grant access to a user, group, or role, select the Allow check box. Tip: To allow everyone to see all objects unless specifically denied access, select the Allow check box for the Everyone role. 4. Click OK. A list of new and updated object-based packages appears.

Steps to Remove Object-Based Security for an Individual Object

1. Right-click the secured object and click Specify Security Rights. 2. Remove security rights by clearing both the Allow and Deny check boxes for all users, groups, or roles. 3. Click OK. A list of packages that will be affected by these changes appears.

Add Package Security

You can define metadata security when you create and publish packages in Framework Manager. You can also define metadata security after creating the package. A package is a secured subset of a project. A package can be published and can be included in other packages. You can add entries that were created in both third-party authentication providers and Cognos 8 as members of a Cognos group. You can organize your security by specifying which users, groups, and roles have access to certain parts of the published model. To add metadata security: Decide whether the objects can be selected, unselected, or hidden in the package (p. 197).

Add users, groups, and roles to the package (p. 199). Decide which users will have administrative access to a package.
When you apply administrative access to a package, you give access to the user or users who are responsible for republishing a package in Framework Manager to the Cognos 8 server ensuring that no reports are impacted when a Framework Manager package is republished to the server

Steps
1. Right-click the package you want and click Edit Package Access. User Guide 203

Chapter 6: Making Metadata Available to Report Authors 2. If you want to create, add, or remove a user, group, or role, click the User Access tab. For more information, see "Add a User, Group, or Role" (p. 199). 3. If you want to grant administrative access to a user, group, or role, click the Administrator Access tab. 4. Click OK.

Explore a Package
When you have a large number of projects and object-based security in a project, it can be difficult to keep everything organized. You can use explore packages to see the packages and roles in a project. In the Package Explorer, you see a list of all the packages (normal and object-based) in a project, as well as the objects that were selected, unselected, or hidden for each package. In the Roles Explorer, you see a list of all the users, groups, and roles in a project, and in which package the object-based security is applied. You can also see whether the objects in the project are hidden or visible to that specific user, group, or role.

Steps
1. From the Actions menu, click Package and click Explore Packages. 2. Choose what you want to do. Goal View the contents of a package Edit the package Action Click the Package Contents tab. Click the Package Contents tab, select the package and click the Edit button. For more information, see "Create or Modify a Package" (p. 197). View who has access to each package View the security for each package 3. Click Close. Click the Package Access tab. Click the Object Security tab and select a package.

View the Distribution of an Object in Packages

When you view the package inclusion of an object, you see, by package, where that object exists and whether it is selected, unselected, or hidden in that package. If the object is secured, you will also see the object-based package in which the object exists.

Steps
1. Click on the object you want to see, and from the Actions menu, select Edit Package Inclusion. 2. To edit the package, click Edit Package. For more information, see "Create or Modify a Package" (p. 197). 3. Click OK.

Specify Languages
You can specify which languages are published with each package. You can create several packages based on the same model, each using a different language.

204

Framework Manager

Chapter 6: Making Metadata Available to Report Authors For example, the package for the Mexican sales office includes Spanish and English. The package for the Canadian sales office includes French and English. You can also specify the languages for all packages at one time. You must add languages to the project (p. 107) before you can specify the languages that report authors require in packages.

Steps for One Package

1. In the Project Viewer, click the package you want to modify. 2. In the Properties pane, locate the Language property and click Click to edit. 3. Click one or more languages and use the arrow buttons to move them from the Available Project Languages box to the Selected Languages box. Tip: To select more than one language, use Ctrl+click. 4. Click OK.

Steps for All Packages

1. 2. 3. 4. In the Project Viewer, click on the Packages folder. From the Actions menu, click Packages and click Specify Package Languages. Select the check box for the language you want for each package. Click OK.

Externalizing Query Subjects and Dimensions

When publishing a package, you have the option to externalize query subjects and dimensions into formats that you can use in Transformer or other applications. Special considerations must be given when externalizing models based on SAP BW metadata. For more information, see "Guidelines for Externalizing SAP BW Dimensions" (p. 361). You first define how each object will be externalized by specifying a method to use. When you publish the package, you specify that the query subjects and dimensions are to be externalized. If you specified a maximum number of rows to be retrieved in the Governors dialog box, this setting is ignored. Excluded or hidden objects that are necessary to connect the included objects in a query path are included in the externalized project. You have several options for the externalization method.

The CSV Method

Use the CSV method to generate a comma separated file that contains the results of the query subject. In a CSV file, the first row represents the column names and each of the following rows contains one record from the query result set. One file is generated for each query subject or dimension that is set to be externalized. With the CSV method, you can use locally processed functions to create a dataset for use in Transformer. You can process Cognos SQL locally or on the data source, and capture the result set in a file that can be used in Transformer. The generated file is restricted to 2 GB in size and contains data based on the native encoding of the current operating system. For example, for Windows 2000, this is specified by the default system locale in the Windows regional settings. For Windows XP and 2003, this is specified by the language for non-Unicode programs option in the Windows regional settings. This option is intended for use only with Transformer. For any other purpose, we recommend that you use the tab method. To externalize SAP BW query subjects, use the csv method. For more information, see "Guidelines for Externalizing SAP BW Dimensions" (p. 361).

User Guide 205

Chapter 6: Making Metadata Available to Report Authors

The Tab Method

Use the tab method to generate a tab delimited file that contains the results of the query subject or dimension. The generated file can be used directly as a data source. The generated file contains data based on Unicode using UTF-16 LE (Little Endian) encoding with BOM (Byte Order Mark). One file is generated for each query subject or dimension that is set to be externalized. This method does not work with Transformer because Transformer does not support Unicode. Use the CSV method to create files for Transformer.

The IQD Method

Use the IQD method to generate a query definition file to be used in Transformer. One file with Native SQL is generated for each query subject or dimension that is set to be externalized. The generated file contains data based on the native encoding of the current operating system. For example, for Windows 2000, this is specified by the default system locale in the Windows regional settings. For Windows XP and 2003, this is specified by the language for non-Unicode programs option in the Windows regional settings. The query subject must not require any local processing. It must be able to be run entirely on the data server. We recommend that you test the query subject by setting the query processing for this data source to database only. An error message then appears if the query subject requires local processing. If you must use locally processed functions to create a dataset, we recommend that you use the CSV method. With the CSV method, you can process Cognos SQL locally or on the data source and capture the result set in a file that can be used in Transformer. Stored procedure query subjects can be externalized for use in Transformer. The stored procedures must not contain any parameters.

The Externalize Auto Summary Property

You can specify that the output be aggregated or grouped or both. By default, Framework Manager returns rows at the detail level without applying any aggregation or grouping. Use the Externalize Auto Summary property to apply the setting of the Regular Aggregate property to query items whose Usage property is set to fact. If you want to have a specific order of items in the Group By clause, specify determinants first, and then set the Externalize Auto Summary property. You can use the Externalize Auto Summary property with all externalize methods. This property is used when you want to have relational data aggregated when it is externalized. Specify determinants for the query subject before externalizing it.

Supported Data Types

Framework Manager supports strings, integers, and dates. It does not support time dimensions. We recommend that you use a date key on the fact query subject in Framework Manager, and let Transformer generate the time dimension.

Shortcuts
If a shortcut is included in a package and it points to a query subject that has been externalized, it will also be externalized. The name of the data file is the name of the query subject that the shortcut points to. If more than one shortcut points to the same query subject, then the query subject is externalized each time the shortcut is encountered.

Query Processing
Native SQL is used to generate an IQD, so the native SQL produced when externalizing must run successfully. Some queries cause more than one query to be issued, or local processing to be performed to retrieve data, or both. To prevent this, ensure that the Query Processing property for all data source objects in the model is set to Database Only. For more information about query processing, see "Improve Performance by Setting Query Processing Type" (p. 69).

206

Framework Manager

Chapter 6: Making Metadata Available to Report Authors

Process to Externalize Dimensions

We recommend that you follow this process to externalize dimensions: Create a model query subject or a data source query subject (p. 90) that contains the dimensions you want to externalize. Add any filters that you require. For more information about creating filters using relational metadata, see "Create a Filter" (p. 122). If you are using SAP BW metadata, see "Create a Filter" (p. 174). In the Properties pane, set the Externalize Method property to the method you want.

Publish the package (p. 207) to externalize the dimensions you selected.

Publish a Package
You can publish a package (p. 197) to the Cognos 8 server for report authors and business authors to use. Report authors use the published package to create standardized reports. Business authors use the package to create ad hoc queries. You can also publish a package to a network location. The package cannot then be used by report authors or business authors. Publishing to a network location can be useful for backing up a package. To avoid potential problems, troubleshoot the package before publishing it by using the Verify the Package Before Publishing check box in the Publish wizard to ensure that it is complete and does not contain any errors. For information about using a published package, see the Report Studio User Guide. When you publish a package, you can set the number of model versions to retain on the server Tip: To see the number of model versions set for a package, select a package and, in the Property pane, find the Max Versions property. externalize query subjects and dimensions so that you can use them with Transformer. For more information, see "Externalizing Query Subjects and Dimensions" (p. 205).

Reports and Model Versions

When you publish a package for the first time, you create a corresponding package on the Cognos 8 server. The package contains a model but no reports. When you publish a package, you can select how many versions of the model you want to retain on the server. The next time you publish the same package, you update the version of the model, in the existing package on the server. New or modified reports use the latest version of the model in the package. When a report is saved, the version of the model used is saved in the report specification. If the package is republished, a report author is notified that the report uses the newest version of the model in the package. The report author must save the report to complete the update. If you open a saved report after the package it is based on is republished, one of two things happens: If the original version of the package still exists, the report runs against the original version. If the original version of the package no longer exists, the report is updated to run against the most recent version. For information about reports, see the Report Studio User Guide.

Steps
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 Framework Manager repository, click Cognos 8 Content Store. To publish the package to a network location, click Location on the network. User Guide 207

Chapter 6: Making Metadata Available to Report Authors 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. 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.

Publish a Package Based on an OLAP Data Source

You use Framework Manager to connect to an OLAP data source and create a package based on a cube. The package is then published directly to the portal making it available to the report author for use in the report authoring tools.

Steps
1. From the Welcome page, click Create a new project. Tip: If you are already in Framework Manager, click New Project from the File menu. 2. In the New Project page, specify a name and location for the project and click OK. You may be prompted to provide authentication information. 3. In the Select Language page, click the design language for the project. The language you select cannot be changed after you click OK, but you can add others. For information about project languages, see "Add a Language to a Project" (p. 108). 4. In the Metadata Wizard dialog box, click Data source and click Next. 5. Select your data source from the list of available data source connections and click Next. If the data source connection is not available in the list, you can click New to create the data source connection. For more information, see "Create a Data Source Connection" (p. 64). 6. Specify a name for the package and click Next. Optionally, you can specify a description and screen tip for the package. 7. Specify who has access to the package. You can add users, groups, or roles (p. 199). 8. Click Finish to import the metadata and create the package. 9. When prompted, click Yes to publish the package to the portal or click No to return to the Project Viewer. The namespace appears in the Project Viewer. You cannot see objects in the native metadata model from within Framework Manager. The native metadata objects are visible from within the report authoring tools when the native metadata package is used.

Analyze the Effects of Changes to a Package

After you create (p. 197) and publish a package (p. 207) in Framework Manager, you can analyze the effects of any changes you made to the package on the reports that were created based on it and saved in the public folder. You can find what changes were made to the package, and see details about each change and which reports are affected by a specific selected change. Note: You cannot analyze the effects of changes to a package if you are using native metadata(p. 62).

Steps
1. Select the published package you want to analyze and, from the Actions menu, click Package, Analyze Publish Impact. 208 Framework Manager

Chapter 6: Making Metadata Available to Report Authors 2. Choose what you want to view. Goal Action

View the change details for an object In the Changed Model Items box, click an item under Change. View report dependencies For each object you select in the Changed Model Items box, click Find Report Dependencies. Repeat for each object.

3. Click Close.

User Guide 209

Chapter 6: Making Metadata Available to Report Authors

210

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Framework Manager is a metadata modeling tool. A model is a business presentation of the information in one or more data sources. When you add security, multilingual metadata, and dimensional metadata to this business presentation, one model can serve the reporting, ad hoc querying, and analysis needs of many groups of users around the globe. A key goal of preparing metadata for business intelligence is to leverage existing metadata while adding value so that your users can find the information that they need. Cognos 8 enables business intelligence on normalized and denormalized relational data sources as well as a variety of OLAP data sources. This document addresses some fundamental concepts for modeling relational data sources in Framework Manager and outlines our recommendations for modeling metadata for use in business reporting and analysis. You can use Framework Manager to model any relational data source dimensionally. Although it is not mandatory that a dimensional schema be used in Cognos 8, many features were added to help you leverage the benefits of dimensional schemas as well as to create a logical dimensional view of non-dimensional schemas.

Scenarios
The topics in this document are organized according to different scenarios. Use the one that matches your goals.

Dimensional Modeling of Relational Data Sources

Dimensional modeling of relational data sources is a capability made available by Cognos 8 Framework Manager. ReportNet 1.x enabled multiple-fact querying and prevented double-counting, and Cognos 8 introduces features designed explicitly for dimensional modeling. It is now possible to model dimensions with hierarchies and levels and to have facts with multiple measures. You can then relate the dimensions to the measures by using scope in the model. For more information, see "Dimensional Modeling of Relational Data Sources" (p. 213).

Upgrading a Best Practices Model from ReportNet 1.x

If your model was built using the best practices from ReportNet 1.x, most of the upgrade to the new functionality of Cognos 8 can be performed in Framework Manager. The Verify Model command was enhanced so that you can select objects in the model and automatically convert them to Cognos 8 dimensions. This leverages the metadata available in the existing model. You can stay with query subjects and have ReportNet 1.x dimension information translated into determinants, or you can move forward to dimensions. If you move forward to dimensions, the existing dimension information in your model is used to create the first hierarchy and levels. For more information, see "Upgrading a Best Practices Model from ReportNet 1.x" (p. 229).

New Objects in Cognos 8

In ReportNet 1.x, dimension information combined the concept of uniqueness with the concept of dimensional hierarchies. In Cognos 8, the concept of dimension information is divided to provide control over uniqueness and granularity. This control is required for relationally-based query subjects and to more explicitly address dimensional concepts of hierarchies and levels for dimensional objects, even on relational sources. When reviewing dimension information, you must understand how the dimension information is applied to the query subject and how the query subject will be used in the Cognos 8 model. User Guide 211

Chapter 7: Guidelines for Modeling Metadata New objects have been introduced in Cognos 8: determinants for query subjects regular dimensions measure dimensions scope relationships Determinants are not the same as levels and hierarchies but they can be closely related to a single hierarchy. The query engine evaluates determinants from first to last. One or more determinants may be specified. If a model regular dimension is based on a query subject with determinants specified, we recommend that one level correspond to each determinant that exists in the query subject the order of the levels in the hierarchy reflect the order of the determinants This results in a consistent model, facilitating upgrading the model in future releases of Cognos products.

Determinants
A determinant is the set of database columns (query items) that can be used to uniquely identify a set of data. Determinants are imported based on key and index information in the data source. We recommend that you always review the determinants that are imported. Use a determinant when you want to do the following: Add information about functional dependencies between columns to avoid double-counting. Specify the granularity of a denormalized query subject to control grouping and double-counting when using model dimensions. For example, some facts join to time on month and some facts join to time on day. Specify determinants for time to clearly capture the functional dependency between month and day as a minimum to prevent double-counting for those facts that join at the month key. Uniquely identify the row of data when retrieving text blob data from the data source. Override the determinants imported from the data source that conflict with relationships created for reporting. For example, there are determinants on two query subjects for multiple columns but the relationship between the query subjects uses only a subset of these columns. Modify the determinant information of the query subject if it is not appropriate to use the additional columns in the relationship. For more information, see "Defining Dimensions and Determinants" (p. 222).

Regular Dimension
A regular dimension contains descriptive and business key information and organizes the information in a hierarchy, from the highest level of granularity to the lowest. It usually has multiple levels and may have multiple key segments to define a level. It may also have multiple hierarchies. Only a single hierarchy can be defined on a data source regular dimension. Multiple-fact querying is enabled with conformed dimensions.

Measure Dimension
A measure dimension is a collection of facts. You can create a measure dimension for one or more query subjects that have a valid relationship between them.

212

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Scope Relationship
Scope relationships exist between measure dimensions and regular dimensions to define the level at which the measures are available for reporting. Scope relationships govern the reporting granularity of the regular dimension for a particular measure dimension. Scope relationships are mandatory between measures and dimensions when reporting. The absence of a scope relationship results in an error at runtime. Scope relationships are for reporting purposes. They are not the same as joins and do not impact the Where clause. You can use scope relationships to include or exclude the regular dimension from the star schema group. Shortcuts cannot be created for scope relationships. Scope relationships can exist only between regular and measure dimensions. Scope relationships can also be created for shortcuts to dimension objects. When shortcuts to dimensions are used, the scope is derived from the scope of the target objects unless scope has been explicitly defined on the shortcuts.

Dimensional Modeling of Relational Data Sources

You must dimensionally model a relational data source when you want to do one or more of the following: use Analysis Studio enable drill functionality in reports improve control over query granularity access member functions in the report authoring tools We recommend that you follow this workflow when you dimensionally model relational data sources: Import the metadata.

Check the imported metadata (p. 213). Customize the metadata. Simplify the model using dimensional concepts (p. 216). Resolve ambiguous relationships (p. 218). Define dimensions and determinants (p. 222). Organize the model by creating business views. Create star schema groups (p. 228). Apply security. Create packages and publish metadata.

For information about the topics not covered here, see "Designing a Project", "Preparing Relational Metadata for Use in Reports", and "Making Metadata Available to Report Authors" in the Framework Manager User Guide. All examples in this document use the database view of the gosales_goretailers normalized model or the import view of the go_data_warehouse model, which are included with the Cognos 8 samples.

Checking Imported Metadata

After importing metadata, you must check the imported metadata in these areas: relationships and cardinality the Usage property for query items the Regular Aggregate property for query items Relationships and cardinality are discussed here. For information on the Usage and Regular Aggregate properties, see "Modifying the Properties of Query Items" in the Framework Manager User Guide.

User Guide 213

Chapter 7: Guidelines for Modeling Metadata Cardinality is combined with dimensions to control how queries are generated so that you can prevent double-counting automatically resolve loop joins enable cross-fact querying for reporting and analysis You can create model dimensions and data source dimensions. Model dimensions are built on a foundation of query subjects that use determinants and relationships with cardinality. Data source dimensions contain their own SQL and use hierarchy and level information as well as relationships with cardinality to define query granularity. Cardinality drives query behavior by allowing rules to be applied regarding the granularity of data that is returned by an individual object and the consequence of joins between objects. The cardinality specified in the relationship between query subjects or dimensions determines how and when Cognos 8 generates stitched queries. Stitched queries are needed for multiple-fact querying across conformed dimensions and across different levels of granularity.

Detecting Cardinality from the Data Source

When importing from a relational data source, cardinality is detected based on a set of rules that you specify. The available options are use primary and foreign keys use matching query item names that represent uniquely indexed columns use matching query item names The most common situation is to use primary and foreign keys as well as matching query items that represent uniquely indexed columns. The information is used to set some properties of query items as well as to generate relationships. To view the index and key information that was imported, right-click a query subject or regular dimension and click Edit Definition. For a query subject, you can change the information in the Determinants tab. All regular dimensions begin as query subjects. If you converted a query subject to a regular dimension, note that determinant information for the query subject is leveraged as a starting point to define the levels of a single hierarchy. We recommend that you review the levels and keys created in the hierarchy of the dimension. Optional relationships, full outer joins, and many-to-many relationships can be imported from your data source. Framework Manager will execute them as queries. Reflexive relationships can be imported from your data source and appear in the model but Framework Manager does not execute them as queries. Although you can view the metadata that defines the reflexive relationship, you cannot edit a reflexive relationship in Framework Manager. For more information, see "Reflexive and Recursive Relationships" (p. 221).

Cardinality in Generated Queries

Framework Manager supports both minimum-maximum cardinality and mandatory-optional cardinality.
0:1 - 0 is the minimum cardinality, 1 is the maximum cardinality 1:n - 1 is the minimum cardinality, n is the maximum cardinality

A relationship with cardinality 1-n can be specified as 1:1 to 1:n when reading the maximum cardinalities. The minimum cardinality of 1 is set to 0 for optional data. Therefore a 1-n relationship can also be specified as 0:1 to 0:n, 0:1 to 1:n, or 1:1 to 0:n. The basic rules for how cardinality is used are the following: Cardinality is applied in the context of a query, meaning that only the cardinalities of items explicitly included in the query are evaluated. 1-n cardinality implies fact on the n side and implies dimension on the 1 side. A query subject can behave as a dimension in one query and as a fact in another. Queries on more than one fact will result in a stitched query. For more information, see "Single Fact Query" (p. 237) and "Multiple-fact, Multiple-grain Query on Conformed Dimensions" (p. 238).

214

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Modeling 1-n Relationships as 1-1 Relationships

If a 1-n relationship exists in the data but is modeled as a 1-1 relationship, SQL traps cannot be avoided because the information provided by the metadata to the query engine is insufficient. The most common problems that arise if 1-n relationships are modeled as 1-1 are the following: Double-counting for multiple-grain queries is not automatically prevented. Cognos 8 cannot detect facts and then generate a stitched query to compensate for double-counting, which can occur when dealing with hierarchical relationships and different levels of granularity across conformed dimensions. Multiple-fact queries are not automatically detected. Cognos 8 does not have sufficient information to detect a multiple-fact query. For multiple-fact queries, an inner join is performed and the loop join is eliminated by dropping the last evaluated join. Dropping a join is likely to lead to incorrect or unpredictable results depending on the dimensions and facts included in the query. You can work around these issues in Report Studio by creating an inner or outer join between queries. This requires the report author to have detailed knowledge of the data. There is no workaround available in Query Studio or Analysis Studio.

Analyzing the Model for Facts and Dimensions

To dimensionally model a relational data source for the purpose of cross-fact querying and analysis, you must examine the underlying schema and address areas where the role of an object as a fact or a dimension is not clear. This examination can result in creating a logical layer to present the data as a star schema. Or you may decide to make changes to the physical data source to deliver a higher performance application. Physical changes may include consolidating tables by using extract-transform-load tools or creating materialized views for frequently-used aggregations. In a relational data source that was not de-normalized using star schema concepts, you may need to analyze the cardinality of the imported query subjects before creating dimensions or converting query subjects to dimensions. You must first understand the business applications of the underlying data as well as understand how Cognos 8 generates queries. Within the context of a query, a query subject with a cardinality of n on all its 1-n relationships to other query subjects can be regarded as a fact. This implies that there are more rows of data in the fact query subject than in the related query subject on the 1 side of the relationship. Any query subject on the 1 side of a 1-n relationship to another query subject is treated as a dimension. The following examples show how schemas can be interpreted. In the first two examples, we see that Sales Staff can relate directly to Sales Fact but can also relate to Sales Fact through Sales Branch. Multiple sales staff belong to a sales branch and staff can belong to different sales branches over time. To correctly determine the sales for a branch at a given time, Sales Branch must be joined directly to Sales instead of being joined through Sales Staff.

Example 1
In this example, all four query subjects are included in a query. The diagram shows that the query subjects having only n cardinalities are treated as facts. Sales Staff and Order Details are treated as facts. Order Header and Sales Branch are treated as dimensions.

User Guide 215

Chapter 7: Guidelines for Modeling Metadata

Example 2
In this example, only three query subjects are included in a query. Order Details is not used in the query. Order Header is now treated as a fact. Sales Staff continues to be treated as a fact.

Example 3
This example shows different query subjects. Arrows point to the query subjects whose cardinality indicates that they are always facts. Areas where the behavior is dependent on the context of the query are circled. All other query subjects behave as dimensions in all queries.

For more information, see "The SQL Generated by Cognos 8" (p. 237).

Simplifying the Model Using Dimensional Concepts

These rules apply when modeling with query subjects or dimensions: Create a regular dimension for groups of query subjects that have hierarchical relationships representing a single business concept (p. 217). Create a measure dimension for groups of query subjects that have factual data sharing many regular dimensions or having a master-detail type of relationship (p. 217). Use the cardinality rules to identify areas of the model where the role of an object as fact or dimension is not clear. For more information, see "Cardinality in Generated Queries" (p. 214). The result of simplifying the model should be a layer of regular and measure dimensions that clearly represent the data in terms of business concepts and ensure predictable query generation. If your data source contains fact-to-fact relationships, we recommend that you handle these in the data source.

216

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Creating Regular Dimensions

Normalized or snowflaked data sources often have several tables that describe a single business concept. For example, a normalized representation of Product may include four tables related by 1-n relationships. Each Product Line has one or more Product Types. Each Product Type has one or more Products. Products have names and descriptions in multiple languages so they exist in a Product Lookup table.

An end user may not know the relationship between the individual query subjects. In addition, having to expand each query subject or dimension and select a query item requires more clicks for the end user. When modeling dimensionally, you can create a regular dimension for Product that simplifies using Product for the purpose of ad hoc query and reporting, and presents the levels of the hierarchy as a visual cue about the relationship between the levels. If you are maintaining a ReportNet 1.x model, you can create a model query subject with determinants instead of a regular dimension. You can replicate the presentation effect of levels by using query item folders. The resulting model query subject can be converted to a regular dimension at any time.

Creating Measure Dimensions

Data sources often have master-detail tables that contain facts. An example is Order Header and Order Detail. When these tables are used to insert and update data, this structure is beneficial. When these tables are used for reporting and analysis, combine them in a single business concept to simplify the model.

To simplify the model in this example, create a model query subject that combines the foreign keys of both Order Header and Order Details and includes all measures at the Order Detail level. Then create a measure dimension based on the model query subject.

User Guide 217

Chapter 7: Guidelines for Modeling Metadata You must always resolve ambiguously identified dimensions and facts. For more information, see "The SQL Generated by Cognos 8" (p. 237).

Resolving Ambiguous Relationships

Ambiguous relationships occur when the data represented by a query subject or dimension can be viewed in more than one context or role. The most common ambiguous relationships are: multiple valid relationships (p. 218) reflexive and recursive relationships (p. 221) You can resolve ambiguous relationships in Framework Manager, or the database administrator can fix them in the data source. For example, the database administrator can remove extra relationships, although this may not be practical. Resolving ambiguous relationships in the model involves determining which query path to use.

Multiple Valid Relationships

A table with multiple valid relationships between itself and another table is known as a role-playing dimension. Multiple valid relationships often occur between regular dimensions and measure dimensions. This is most commonly seen in dimensions such as Time and Customer. For example, the Sales fact has multiple relationships to the Time dimension on keys such as Order Day, Ship Day, and Close Day.

Steps
1. 2. 3. 4. 5. 6. Leave all the relationships in place in the Import View. Create a measure dimension for the fact. Create a regular dimension for each of the dimensions. Create or copy the regular dimension for each role. Rename the dimension, hierarchy, levels, and attributes appropriately for their use. Ensure that a single appropriate relationship exists between each regular dimension and the measure dimension, or between the underlying query subjects. 7. Ensure that there is a corresponding scope relationship specific to each role.

218

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

8. Decide how you want to use these roles with other facts that do not share the same concepts. For example, Product Forecast has only one time key. You can do one of the following: Designate a specific time dimension to be the conformed time dimension. You can pick the most common role that you will use and name it clearly as a conformed dimension. You can then ensure that this version of the dimension is joined to all facts requiring a time dimension.

User Guide 219

Chapter 7: Guidelines for Modeling Metadata

You can treat ship day, order day and close day as interchangeable time dimensions with Product Forecast fact. In this case, you must create joins between the role-playing dimensions and Product Forecast fact. You can use only one time dimension at a time when querying the Product Forecast fact or your report may contain no data. For example, Month_key=Ship Month Key (200401) and Month key=Close Month Key (200312).

220

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Model Objects vs. Shortcuts

You can create model objects based on the original query subjects. These model objects can be model regular dimensions or model query subjects. Or you can create shortcuts. Use model regular dimensions or model query subjects when you want to create custom views of the same query subject. Use shortcuts when you want exact replicas of a regular dimension or query subject in more than one place. A shortcut that exists in the same folder as its target behaves as an alias, or independent instance. However, a shortcut existing elsewhere in the model will behave as a reference to the original. This approach is less flexible overall from a presentation perspective because renaming can only be done at the object level.

Reflexive and Recursive Relationships

Reflexive and recursive relationships imply two or more levels of granularity. Framework Manager imports reflexive relationships but does not use them when executing queries. Reflexive relationships, which are self-joins, are shown in the model for the purpose of representation only. To create a functioning reflexive relationship, you must create an alias using either a shortcut to the query subject in the same folder, or a model query subject based on the query subject. You then create a relationship between the query subject and the alias. Using a model query subject tends to be a better option because you can specify which query items are included in the query subject. For example, the Staff query subject has a recursive relationship between Staff Key and Manager Key.

Steps
1. Create a model query subject to represent Manager. 2. Select which query items apply to Manager and rename them in a meaningful way. 3. Create a relationship with a 1:1 to 1:n between Staff and Manager. User Guide 221

Chapter 7: Guidelines for Modeling Metadata For a simple two-level structure using a model query subject for Manager that is based on Staff, the model looks like this:

4. For a recursive hierarchy, repeat these steps for each additional level in the hierarchy. For a deep recursive hierarchy, we recommend that the hierarchy be flattened in the data source and that you model the flattened hierarchy in a single regular dimensions. 5. Select the query subjects, right-click, and click Merge in New Regular Dimension.

Defining Dimensions and Determinants

Use dimensions and determinants to ensure that the aggregation in reports is correct and that queries generate correctly. Use regular dimensions to organize and present descriptive information to guide the end user experience in the report authoring tools. Hierarchies are presented in a top-down format, from the coarsest level of granularity to the finest. Data source regular dimensions treat hierarchy and level information as if they are determinants. Model regular dimensions require determinants to be specified for the underlying query subjects. Use determinants to specify which data is unique. If a determinant defines attributes, all query items in the query subject must be defined as either a key or an attribute. You can have a determinant with no attributes defined for it. Framework Manager uses this type of determinant to indicate which query items are indexed. Joins and granularity are the key factors in SQL generation. Specify granularity for the objects that have relationships by using either a hierarchy or determinants on the object to which the join is created. You must use regular and measure dimensions to enable analysis on your relational data source. In most data sources, regular dimensions, which contain descriptive information, are likely to be shared by more than one measure dimension. Regular dimensions are often called shared dimensions. Regular and measure dimensions organized into a cluster is often referred to as a star schema group but can also be referred to as a functional or subject area group. Measure dimensions are related to each other through the regular dimensions. To create reports that fully compare and contrast functional areas, you may need to use more than one measure dimension in a report. When querying across star schemas or functional areas, you must consider the role the hierarchy plays in query generation: Multiple-fact, multiple-grain queries (p. 223) Multiple hierarchies (p. 227)

222

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Multiple-fact, Multiple-grain Queries

Multiple-fact, multiple grain queries occur when dimensions are related to multiple fact tables at different levels. A dimension typically has distinct levels of attribute data with business keys that have a hierarchical relationship to each other. The report authoring tools automatically aggregate to the lowest common level present in the report. The hierarchical relationship between level keys is used to aggregate data to the lowest level included in the report. The potential for double-counting arises when creating totals on columns that may contain repeated data. When the level of granularity of the data is modeled correctly, double-counting can be avoided. Note: You can report data at a level of a hierarchy below which it exists. This causes the data to repeat across members at that level, but the totals are not affected. This example shows two data source measure dimensions, Sales and Product forecast, that share two regular dimensions, Time and Product.

The Time dimension is the focal point of the granularity issue in this example. In the underlying data source, Sales is joined to Time on the Day key, and Product forecast is joined to Time on the Month key. Because of the different join keys, a minimum of two levels must be clearly identified with keys for the Time Dimension.

Data Source Dimensions

When using data source dimensions, we recommend that you create all levels that may be necessary for reporting instead of only those levels that are immediately necessary. For example, the levels for Month and Day have their keys identified. Day is the lowest level of the hierarchy, and the Unique Level box is selected because this data is unique in the underlying data source. For example, the level definitions for Month are as follows.

User Guide 223

Chapter 7: Guidelines for Modeling Metadata

For example, the level definitions for Day are as follows.

The Product dimension has three levels: Product line, Product type, and Product. It has relationships to both fact tables on the Product key. All joins in the underlying tables occur on the Product key so there are no granularity issues for this dimension. Any hierarchy that you create is purely for the purpose of drilling and rollup.

224

Framework Manager

Chapter 7: Guidelines for Modeling Metadata By default, a report is aggregated to retrieve records from each fact table at the lowest common level of granularity. If you create a report that uses Quantity from Sales, Expected volume from Product forecast, Month_name from the Time dimension, and Product_name from the Product dimension, the report retrieves records from each fact table at the lowest common level of granularity. In this example, it is at the month and product level. If you do not specify the levels of the hierarchy properly in the Time dimension, incorrect aggregation may occur. For example, Expected volume values that exist at the Month level in Product forecast is rolled up based on the lower time level, days, in the Time dimension. The values for Expected volume are multiplied by the number of days in the month.

To prevent double-counting when data exists at multiple levels of granularity, create a hierarchy for the Time dimension and correctly specify the levels with keys. Note the different numbers in the Expected Volume column. Double-counting was prevented.

Model Regular Dimensions and Query Subjects with Determinants

Determinants are not the same as levels and hierarchies but they can be closely related to a single hierarchy. The query engine evaluates determinants from first to last. One or more determinants may be specified. If a model regular dimension is based on a query subject with determinants specified, we recommend that one level correspond to each determinant that exists in the query subject the order of the levels in the hierarchy reflect the order of the determinants This results in a consistent model, facilitating upgrading the model in future releases of Cognos products. When using model dimensions, you begin with the query subjects that are the basis for the dimension. We recommend that you create a determinant for each level that may be necessary for reporting instead of only those levels that are immediately necessary. For example, here is a solution for the Time dimension that is an alternative to using dimensions as previously described. Determinants are defined for Month and Day. Note that Day is the lowest level of the hierarchy. For example, the determinants for Month are as follows.

User Guide 225

Chapter 7: Guidelines for Modeling Metadata

For example, the determinants for Day are as follows.

The Uniquely Identified check box is selected for only the lowest level of the hierarchy because the data in this column is unique for every row in the underlying data source. The Group By check box is selected for all levels whose data is not unique. If aggregation on an associated attribute is required, the key defined for the determinant should be used in a Group By clause in the query. Also, if an attribute of a Group By level is included in a query, a Minimum aggregate function may be used to ensure that the value is unique in the query. The hierarchy for the model regular dimension would be the same as the one shown for the data source dimension. For information about the SQL and the results generated for this example, see "Multiple-fact, Multiple-grain Query on Conformed Dimensions" (p. 238).

226

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Multiple Hierarchies
Multiple hierarchies occur when different structural views can be applied to the same data. Depending on the nature of the hierarchies and the required reports, you may need to evaluate the modeling technique applied to a particular case. You can specify multiple hierarchies on regular dimensions in Framework Manager. Multiple hierarchies for a regular dimension behave as views of the same query. You cannot use the different hierarchies of the same dimension in a single report query. For example, sales staff can be viewed by manager or geography. In the report authoring tools, these hierarchies are separate but interchangeable logical structures, which are bound to the same underlying query. Here is sales staff as a single dimension with two hierarchies:

The hierarchies are defined in Framework Manager as follows.

If you need more than one hierarchy from a dimension in a report, such as on opposing axes, you must create a regular dimension for each hierarchy. Each regular dimension must be a single distinct hierarchy. In this way, you can issue the same, or slightly different, block of SQL multiple times. Here are separate dimensions for each hierarchy.

User Guide 227

Chapter 7: Guidelines for Modeling Metadata

Use this approach if dramatically different sets of columns are relevant for each hierarchy and it is more intuitive for end users to model the hierarchies as separate dimensions with separate and simpler queries.

Creating Star Schema Groups

Star schema groups can make the model more intuitive for end users by indicating which regular dimensions and measure dimensions are related. Star schema groups can also facilitate multiple-fact reporting by indicating how to use regular dimensions that are common to many measure dimensions. Multiple-fact reporting is also known as cross-functional reporting. Star schema groups also provide context for queries with ambiguous joins. By creating star schema groups in the business view of the model, you can clarify which join path to select when multiple join paths are available. This is particularly useful for fact-less queries.

Multiple Conformed Star Schemas or Fact-less Queries

You will likely see conformed regular dimensions between measure dimensions. Join ambiguity is an issue when you report using items from multiple dimensions without including any items from the measure dimension. This is called a fact-less query. For example, Product and Time are regular dimensions related to the Product forecast and Sales measure dimensions.

Using these relationships, how do you write a report that uses only the Product and Year items? The business question could be which products were forecasted for sale in 2005 or which products were actually sold in 2005. Although this query involves only the Product and Time dimensions, these dimensions are related through multiple measure dimensions. There is no way to guess which business question is being asked. You must set the context for the fact-less query. In this example, we recommend that you create two namespaces, one containing Product, Time, and Product forecast, and another containing Product, Time, and Sales.

228

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

When you create these namespaces, use the Create Star Schema Grouping wizard to select the correct dimensions for each measure, create shortcuts for all objects, and move the shortcuts to a new namespace. When you do this for all star schemas, you resolve join ambiguity by placing shortcuts to the measure dimension and all regular dimensions in a single namespace. The shortcuts for conformed dimensions in each namespace are identical and are references to the original object. With a namespace for each star schema, it is now clear to the end users which items to use. To create a report on Products Sold in 2005, they use Product and Year from the Sales Namespace. The only relationship that is relevant in this context is the relationship between Product, Time, and Sales Fact, and it is used to return the data.

Upgrading a Best Practices Model from ReportNet 1.x

Part of the Cognos 8 installation was to automatically update all published models to work in Cognos 8. To begin reporting, you do not need to modify these models. When you want to reflect changes in the data or metadata or use new features, you must explicitly upgrade the model in Framework Manager. When you upgrade, you must decide when and where to use new features. Tools in Framework Manager help you upgrade to new features based on the existing metadata in the model. If you used the modeling recommendations in the Modeling in Framework Manager for Predictable Queries and Results paper, which is available from the Cognos support Web site (http://support.cognos.com), to create the ReportNet 1.x model, we recommend the following workflow: Review the existing model (p. 230).

Upgrade the model (p. 230). Define dimensions and determinants (p. 222). Create measure dimensions or convert facts to measure dimensions. Create and test star schema groups (p. 228). Republish the metadata.

For information about the topics not covered here, see "Preparing Relational Metadata for Use in Reports" and "Making Metadata Available to Report Authors" in the Framework Manager User Guide. All examples in this document use the database view of the gosales_goretailers normalized model or the import view of the go_data_warehouse model, which are included with the Cognos 8 samples.

User Guide 229

Chapter 7: Guidelines for Modeling Metadata

Reviewing the Existing Model

In ReportNet 1.x, dimension information combined the concept of uniqueness with the concept of dimensional hierarchies. In Cognos 8, the concept of dimension information is divided to provide control over uniqueness and granularity. This control is required for relationally-based query subjects and to more explicitly address dimensional concepts of hierarchies and levels for dimensional objects, even on relational sources. When reviewing dimension information, you must understand how the dimension information is applied to the query subject and how the query subject will be used in the Cognos 8 model. Before upgrading the model to Cognos 8, we recommend that you review the ReportNet 1.x model using the Modeling in Framework Manager for Predictable Queries and Results paper. You must ensure that dimension information was specified correctly. The upgrade process uses the dimension information to create dimensions or determinants. Dimensions and determinants are the means of controlling granularity and automatic aggregation as well as preventing double-counting in Cognos 8. We highly recommend that you run the Verify Model command in ReportNet 1.x. Repair all errors and review all warnings before you start the upgrade.

Upgrading the Model

After Cognos 8 automatically upgrades the model, you must manually review the new features because some alter query behavior. The initial automated upgrade to Cognos 8 is designed to produce a model that can be published to a Cognos 8 report server. Most changes to modeling concepts in Cognos 8 are in the areas of data types, dimensions, and determinants.

Changes to Data Types

Cognos 8 added support for new data types. This may change how data types are mapped between Cognos and the source data on metadata import. The primary areas of change are as follows: nChar In some cases, data types that were char become nChar. nVarChar In some cases, data types that were varChar become nVarChar. numeric In some cases, data types that were decimal become numeric. timestampTZ In some cases, data types that were varChar become timestampTZ. IntervalTZ In some cases, data types that were varChar become IntervalTZ. Mapping of these data types varies by data source vendor and can be confirmed from the data type support section of the Cognos support Web site (http://support.cognos.com). The Allow enhanced model portability at runtime governor is selected upon initial upgrade. This governor prevents rigid enforcement of data types so that the Cognos 8 model can function as a ReportNet 1.x model until you update the data types in the metadata. It is not possible to automatically determine the new data type based on the existing data types saved in the model. For this reason, use the Verify Model, Verify Selected Objects, or Update Object commands to update the mapping of the data types.

Dimensions and Determinants

In ReportNet 1.x, dimension information combined the concept of uniqueness with the concept of dimensional hierarchies. In Cognos 8, the concept of dimension information is divided to provide control over uniqueness and granularity. This control is required for relationally-based query subjects and to more explicitly address dimensional concepts of hierarchies and levels for dimensional objects, even on relational sources. 230 Framework Manager

Chapter 7: Guidelines for Modeling Metadata When reviewing dimension information, you must understand how the dimension information is applied to the query subject and how the query subject will be used in the Cognos 8 model. The metadata previously specified by dimension information is implicitly preserved in the model and continues to exist for query subjects until those query subjects are repaired. You cannot change this dimension information. You can upgrade the dimension information to regular dimensions or determinants. Until you upgrade the query subject, Cognos 8 query generation uses the dimension information previously specified in ReportNet 1.x. The Allow dynamic generation of dimension information governor is selected upon initial upgrade. This governor ensures consistent behavior with ReportNet 1.x by deriving a form of dimension information from the relationships, key information, and index information in the data source. For more information, see "New Objects in Cognos 8" (p. 211).

Checking and Repairing the Model

After automatically updating the metadata, Framework Manager prompts you to check the model. We highly recommend that you complete this step before making any changes to the model.

Understanding Warnings
The following warnings commonly appear when you check a ReportNet 1.x model: Needs reevaluation This message is most likely related to data type changes. The majority of items with this warning can be selected for repair. The repair option steps you through your options for evaluating and upgrading specific elements of metadata. Tip: You can also evaluate a query subject by using the Evaluate Object command from the Tools menu. Join expression conflicts with the determinant information defined in the query subject Sometimes the index and key information specified for a query subject implies a level of granularity that does not match the relationships specified on a query subject. For more information, see "Defining Dimensions and Determinants" (p. 222). None of the query items in this level have a role Caption specified When defining levels, you must ensure that a business key and caption roles are specified. These roles are relevant for member functions in the report authoring tools and to assist in the member-oriented tree in Analysis Studio. One or more determinants that describe the keys and attributes of the query subject should be specified When importing from a relational data source, determinants are specified for any indexes and keys that exist in the data source. It is possible that no determinants exist on a query subject upgraded from ReportNet 1.x, especially for model query subjects. We recommend that you use determinants to explicitly specify the granularity of the data in the query subject and the functional dependencies between query items. However, it is not mandatory to specify determinants for query subjects representing a single level or fact data. Determinants are required only if the item is a BLOB data type.

Selecting and Repairing Objects

You can select all items with check boxes and repair them. The repair process first evaluates all selected items. This evaluation automatically resolves issues around new data types and prompts you to deal with dimension information in the model. We recommend that you upgrade most query subjects that used dimension information in ReportNet 1.x to dimensions.

Converting Query Subjects to Dimensions

You can convert a query subject to a dimension by using the dimension information in the query subject. You can also convert a dimension to a query subject with determinants at any time after completing the upgrade.

User Guide 231

Chapter 7: Guidelines for Modeling Metadata Dimension information is mapped to regular dimensions as follows. Dimension information Hierarchies Levels Regular dimension Hierarchies Levels The first level of the hierarchy is automatically defined as the All level. It contains a single root member, which represents the top level of the hierarchy. You cannot delete or move the All level. You can change its name, description, and screen tip. Keys Unique Key Alphabetically first text attribute All other attributes _businessKey role Unique Level _memberCaption role Can be manually assigned to be _memberDescription, custom role, or no role

For example, the Product query subject in ReportNet 1.x has the following dimension information.

When you convert this query subject to a regular dimension, the dimension information is used to create these hierarchies and levels in Cognos 8.

232

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Things to Review
After conversion, you must review the following: Unique Level A unique level indicates that the keys of the levels above are not necessary to identify the members in this level. memberCaption role To leverage member functions and enable dragging and dropping levels in the report authoring tools, you must assign a memberCaption to each level in a dimension. Because this role does not exist in ReportNet 1.x, it is mapped where possible. If there are no attributes for the level, the absence of a caption is highlighted when you check the model. Attributes In general, all other attributes should be included in the dimension and associated to the correct level. By default, they are included with no role. You have the option to create custom roles or assign attributes to existing roles. Multiple Hierarchies Only the first hierarchy from a ReportNet 1.x query subject is upgraded to a dimension. You must re-create all other hierarchies. For example, after upgrading the Product query subject to a regular dimension, you can further refine it. In this example, Product name is now defined as the memberCaption role.

User Guide 233

Chapter 7: Guidelines for Modeling Metadata

Converting Dimension Information to Determinants

When maintaining models that do not fully conform to ReportNet 1.x recommendations, you may need to preserve query subjects. Dimension information is then mapped to determinants as follows. Dimension information Hierarchies Levels Determinants Order of determinants. Determinants Uniquely Identified Group By Unique Key is not selected Unique Key is selected Attributes Key segments from higher levels are included in the key. Only the key segment, or segments, for the level are included in the key. Attributes Unassociated attributes are assigned to the last determinant, which generally corresponds to the lowest level. For example, the Product query subject with dimension information looks like this in ReportNet 1.x.

When you convert it to a query subject with determinants, it looks like this.

234

Framework Manager

Chapter 7: Guidelines for Modeling Metadata

Things to Review
After conversion, you must review the following: Uniquely Identified The Uniquely Identified check box indicates that a determinant uniquely identifies a row in the data set. Group By The Group By check box implies a mandatory grouping will be done on any query using this determinant or any item determined by it. This helps to resolve double-counting in the case of dimensions being joined on different keys at different levels of granularity. If attribute items are determined by a determinant that has the Group By check box selected, the Minimum aggregate function is applied to them in the query. Multiple Hierarchies Determinants do not explicitly support the concept of hierarchies and provide no mechanism to represent multiple hierarchies. If two hierarchies existed on a query subject in ReportNet 1.x, only the first hierarchy is upgraded to a determinant. You must create a second query subject and manually specify the determinants for the other hierarchy. For example, after upgrading the Product query subject to use determinants, you can further refine it. In this example, Product key is now the unique identifier, and Product line code and Product type code are used to group query items.

User Guide 235

Chapter 7: Guidelines for Modeling Metadata For more information, see "Defining Dimensions and Determinants" (p. 222).

236

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

The SQL generated by Cognos 8 is often misunderstood. This document explains the SQL that results in common situations.

Understanding Dimensional Queries When Using Best Practices

Dimensional queries are designed to enable multiple-fact querying. The basic goals of multiple-fact querying are: Preserve data when fact data does not perfectly align across common dimensions, such as when there are more rows in the facts than in the dimensions. Prevent double-counting when fact data exists at different levels of granularity by ensuring that each fact is represented in a single query with appropriate grouping. Determinants may need to be created for the underlying query subjects in some cases.

Single Fact Query

A query on a star schema group results in a single fact query. In this example, Sales is the focus of any query written. The dimensions provide attributes and descriptions to make the data in Sales more meaningful. All relationships between dimensions and the fact are 1-n.

When you filter on the month and product, the result is as follows.

User Guide 237

Chapter 8: The SQL Generated by Cognos 8

Multiple-fact, Multiple-grain Query on Conformed Dimensions

A query on multiple facts and conformed dimensions respects the cardinality between each fact table and its dimensions and writes SQL to return all the rows from each fact table. For example, Sales and Product Forecast are both measure dimensions.

Note that this is a simplified representation and not an example of how this would appear in a model built using Cognos best practices.

The Result
Individual queries on Sales and Product Forecast by Month and Product yield the following results. The data in Sales is actually stored at the day level.

A query on Sales and Product Forecast respects the cardinality between each fact table and its dimensions and writes SQL to return all the rows from each fact table. The fact tables are matched on their common keys, month and product, and, where possible, are aggregated to the lowest common level of granularity. In this case, days are rolled up to months. Nulls are often returned for this type of query because a combination of dimensional elements in one fact table may not exist in the other.

238

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

Note that in February 2004, Course Pro Umbrellas were in the forecast but there were no actual sales. The data in Sales and Product Forecast exist at different levels of granularity. The data in Sales is at the day level, and Product Forecast is at the month level.

The SQL
The SQL generated by Cognos 8, known as a stitched query, is often misunderstood. A stitched query uses multiple subqueries, one for each star, brought together by a full outer join on the common keys. The goal is to preserve all dimensional members occurring on either side of the query. The following example was edited for length and is used as an example to capture the main features of stitched queries.
select coalesce(D2.MONTH_NAME,D3.MONTH_NAME) as MONTH_NAME, coalesce(D2.PRODUCT_NAME,D3.PRODUCT_NAME) as PRODUCT_NAME, D2.EXPECTED_VOLUME as EXPECTED_VOLUME, D3.QUANTITY as QUANTITY from (select TIME.MONTH_NAME as MONTH_NAME, PRODUCT_LOOKUP.PRODUCT_NAME as PRODUCT_NAME, XSUM(PRODUCT_FORECAST_FACT.EXPECTED_VOLUME for TIME.CURRENT_YEAR,TIME.QUARTER_KEY,TIME.MONTH_KEY, PRODUCT.PRODUCT_LINE_CODE, PRODUCT.PRODUCT_TYPE_CODE, PRODUCT.PRODUCT_KEY ) as EXPECTED_VOLUME from (select TIME.CURRENT_YEAR as CURRENT_YEAR, TIME.QUARTER_KEY as QUARTER_KEY, TIME.MONTH_KEY as MONTH_KEY, XMIN(TIME.MONTH_NAME for TIME.CURRENT_YEAR, TIME.QUARTER_KEY,TIME.MONTH_KEY ) as MONTH_NAME from TIME_DIMENSION TIME group by TIME.MONTH_KEY) TIME join PRODUCT_FORECAST_FACT PRODUCT_FORECAST_FACT on (TIME.MONTH_KEY = PRODUCT_FORECAST_FACT.MONTH_KEY) join PRODUCT PRODUCT on (PRODUCT.PRODUCT_KEY = PRODUCT_FORECAST_FACT.PRODUCT_KEY) where (PRODUCT.PRODUCT_NAME in ('Aloe Relief','Course Pro Umbrella')) and (TIME.MONTH_NAME in ('April 2004','February 2004','February 2006')) group by TIME.MONTH_NAME, PRODUCT_LOOKUP.PRODUCT_NAME ) D2 full outer join (select TIME.MONTH_NAME as MONTH_NAME, PRODUCT_LOOKUP.PRODUCT_NAME as PRODUCT_NAME, XSUM(SALES_FACT.QUANTITY for TIME.CURRENT_YEAR, TIME.QUARTER_KEY, TIME.MONTH_KEY, PRODUCT.PRODUCT_LINE_CODE, PRODUCT.PRODUCT_TYPE_CODE, PRODUCT.PRODUCT_KEY ) as QUANTITY from select TIME.DAY_KEY,TIME.MONTH_KEY,TIME.QUARTER_KEY, TIME.CURRENT_YEAR,TIME.MONTH_EN as MONTH_NAME from TIME_DIMENSION TIME) TIME join SALES_FACT SALES_FACT on (TIME.DAY_KEY = SALES_FACT.ORDER_DAY_KEY) join PRODUCT PRODUCT on (PRODUCT.PRODUCT_KEY = SALES_FACT.PRODUCT_KEY) where

User Guide 239

Chapter 8: The SQL Generated by Cognos 8

(PRODUCT.PRODUCT_NAME in ('Aloe Relief','Course Pro Umbrella')) and (TIME.MONTH_NAME in ('April 2004','February 2004','February 2006')) group by TIME.MONTH_NAME, PRODUCT.PRODUCT_NAME ) D3 on ((D2.MONTH_NAME = D3.MONTH_NAME) and (D2.PRODUCT_NAME = D3.PRODUCT_NAME))

What Is the Coalesce Statement?

A coalesce statement is simply an efficient means of dealing with query items from conformed dimensions. It is used to accept the first non-null value returned from either query subject. This statement allows a full list of keys with no repetitions when doing a full outer join.

Why Is There a Full Outer Join?

A full outer join is necessary to ensure that all the data from each fact table is retrieved. An inner join gives results only if an item in inventory was sold. A right outer join gives all the sales where the items were in inventory. A left outer join gives all the items in inventory that had sales. A full outer join is the only way to learn what was in inventory and what was sold.

Modeling 1-n Relationships as 1-1 Relationships

If the cardinality were modified to use only 1-1 relationships between query subjects or dimensions, the result of a query on Product Forecast and Sales with Time or Time and Product generates a single Select statement that drops one join to prevent a circular reference. The example below shows that the results of this query are incorrect when compared with the results of individual queries against Sales or Product Forecast. The results of individual queries are as follows.

When you combine these queries into a single query, the results are as follows.

The SQL
If you look at the SQL, you can see that, because Cognos 8 detected that a circular join path exists in the model, it did not include one of the relationships that was not necessary to complete the join path. In this example, the relationship between Time and Product Forecast was dropped. A circular join path rarely results in a query that produces useful results.
select

240

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

TIME_.MONTH_NAME as MONTH_NAME, PRODUCT_LOOKUP.PRODUCT_NAME as PRODUCT_NAME, XSUM(SALES_FACT.QUANTITY for TIME_.CURRENT_YEAR, TIME_.QUARTER_KEY, TIME_.MONTH_KEY, PRODUCT.PRODUCT_LINE_CODE, PRODUCT.PRODUCT_TYPE_CODE, PRODUCT.PRODUCT_KEY ) as QUANTITY, XSUM(PRODUCT_FORECAST_FACT.EXPECTED_VOLUME for TIME_.CURRENT_YEAR, TIME_.QUARTER_KEY, TIME_.MONTH_KEY, PRODUCT.PRODUCT_LINE_CODE, PRODUCT.PRODUCT_TYPE_CODE, PRODUCT.PRODUCT_KEY ) as EXPECTED_VOLUME from (select TIME.DAY_KEY,TIME.MONTH_KEY, TIME.QUARTER_KEY, TIME.CURRENT_YEAR,TIME.MONTH_EN as MONTH_NAME from TIME_DIMENSION TIME) TIME join SALES_FACT on (TIME_.DAY_KEY = SALES_FACT.ORDER_DAY_KEY) join PRODUCT_FORECAST_FACT on (TIME_.MONTH_KEY = PRODUCT_FORECAST_FACT.MONTH_KEY) join PRODUCT (PRODUCT.PRODUCT_KEY = PRODUCT_FORECAST_FACT.PRODUCT_KEY) where (PRODUCT.PRODUCT_NAME in ('Aloe Relief','Course Pro Umbrella')) and (TIME_.MONTH_NAME in ('April 2004','February 2004','February 2006')) group by TIME_.MONTH_NAME, PRODUCT.PRODUCT_NAME

Multiple-fact, Multiple-grain Query on Non-Conformed Dimensions

If a non-conformed dimension is added to the query, the nature of the result returned by the stitched query is changed. It is no longer possible to aggregate records to a lowest common level of granularity because one side of the query has dimensionality that is not common to the other side of the query. The result returned is really two correlated lists.

The Result
The results of individual queries on the respective star schemas look like this.

User Guide 241

Chapter 8: The SQL Generated by Cognos 8

Querying the same items from both star schemas yields the following result.

In this result, the lower level of granularity for records from Sales results in more records being returned for each month and product combination. There is now a 1-n relationship between the rows returned from Product Forecast and those returned from Sales. When you compare this to the result returned in the example of the multiple-fact, multiple grain query on conformed dimensions, you can see that more records are returned and that Expected Volume results are repeated across multiple Order Methods. Adding Order Method to the query effectively changes the relationship between Quantity data and Expected Volume data to a 1-n relationship. It is no longer possible to relate a single value from Expected Volume to one value from Quantity. Grouping on the Month key demonstrates that the result in this example is based on the same data set as the result in the multiple-fact, multiple-grain query but with a greater degree of granularity.

242

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

The SQL
The stitched SQL generated for this example is very similar to the SQL generated in the multiple-fact, multiple-grain query (p. 238). The main difference is the addition of Order Method. Order Method is not a conformed dimension and affects only the query against the Sales Fact table.
select D2.QUANTITY as QUANTITY, D3.EXPECTED_VOLUME as EXPECTED_VOLUME, coalesce(D2.PRODUCT_NAME,D3.PRODUCT_NAME) as PRODUCT_NAME, coalesce(D2.MONTH_NAME,D3.MONTH_NAME) as MONTH_NAME, D2.ORDER_METHOD as ORDER_METHOD from (select PRODUCT.PRODUCT_NAME as PRODUCT_NAME, TIME.MONTH_NAME as MONTH_NAME, ORDER_METHOD.ORDER_METHOD as ORDER_METHOD, XSUM(SALES_FACT.QUANTITY for TIME.CURRENT_YEAR,TIME.QUARTER_KEY, TIME.MONTH_KEY,PRODUCT.PRODUCT_LINE_CODE,PRODUCT.PRODUCT_TYPE_CODE,PRODUCT .PRODUCT_KEY,ORDER_METHOD_DIMENSION.ORDER_METHOD_KEY ) as QUANTITY from PRODUCT_DIMENSION PRODUCT join SALES_FACT SALES_FACT on (PRODUCT.PRODUCT_KEY = SALES_FACT.PRODUCT_KEY) join ORDER_METHOD_DIMENSION ORDER_METHOD on (ORDER_METHOD.ORDER_METHOD_KEY = SALES_FACT.ORDER_METHOD_KEY) join TIME_DIMENSION TIME on ( TIME.DAY_KEY = SALES_FACT.ORDER_DAY_KEY) where (PRODUCT.PRODUCT_NAME in ('Aloe Relief','Course Pro Umbrella')) and ( TIME.MONTH_NAME in ('April 2004','February 2004','February 2006')) group by PRODUCT.PRODUCT_NAME, TIME.MONTH_NAME, ORDER_METHOD.ORDER_METHOD ) D2 full outer join (select PRODUCT.PRODUCT_NAME as PRODUCT_NAME, TIME.MONTH_NAME as MONTH_NAME, XSUM(PRODUCT_FORECAST_FACT.EXPECTED_VOLUME for TIME.CURRENT_YEAR, TIME.QUARTER_KEY, TIME.MONTH_KEY,PRODUCT.PRODUCT_LINE_CODE,PRODUCT.PRODUCT_TYPE_CODE,PRODUCT .PRODUCT_KEY ) as EXPECTED_VOLUME from PRODUCT_DIMENSION PRODUCT join PRODUCT_FORECAST_FACT PRODUCT_FORECAST_FACT on (PRODUCT.PRODUCT_KEY = PRODUCT_FORECAST_FACT.PRODUCT_KEY) join (select TIME.CURRENT_YEAR as CURRENT_YEAR, TIME.QUARTER_KEY as QUARTER_KEY, TIME.MONTH_KEY as MONTH_KEY, XMIN( TIME.MONTH_NAME for TIME.CURRENT_YEAR, TIME.QUARTER_KEY, TIME.MONTH_KEY ) as MONTH_NAME from TIME_DIMENSION TIME group by TIME.CURRENT_YEAR, TIME.QUARTER_KEY, TIME.MONTH_KEY ) TIME on ( TIME.MONTH_KEY = PRODUCT_FORECAST_FACT.MONTH_KEY) where (PRODUCT.PRODUCT_NAME in ('Aloe Relief','Course Pro Umbrella')) and

User Guide 243

Chapter 8: The SQL Generated by Cognos 8

( TIME.MONTH_NAME in ('April 2004','February 2004','February 2006')) group by PRODUCT.PRODUCT_NAME, TIME.MONTH_NAME ) D3 on ((D2.PRODUCT_NAME = D3.PRODUCT_NAME) and (D2.MONTH_NAME = D3.MONTH_NAME))

Resolving Ambiguously Identified Dimensions and Facts

If ambiguously identified dimensions and facts are not resolved, the result could be unpredictable or incorrect queries. These queries could contain double-counted results, result sets that are incorrectly related, and inefficient queries. They can also contain incorrect summaries for queries with multiple facts. In this example, you must resolve the areas that are circled.

You can resolve the circled areas by using a combination of data source and model query subjects. There are some cases that can even be resolved by adding filters to the query subjects that effectively change the cardinality from n to 1. The query subjects you create will form the foundation of a dimensional model.

Resolving Queries That Should Not Have Been Split

If queries are split and should not be split, you must resolve these queries. Query subjects on the n side of all relationships are identified as facts. We can see that in the following example, Order Header and Country Multilingual are behaving as facts. In reality, the Country Multilingual query subject contains only descriptive information and seems to be a lookup table. From a dimensional or business modeling perspective, Country Multilingual is an extension of Country. Why is it a problem to leave the model like this?

244

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

Test this model by authoring a report on the number of orders per city, per country. Using this model returns an incorrect result. The numbers are correct for the cities but some cities are shown as being in the wrong country. This is an example of an incorrectly related result.

Usually the first place to look when you see something like this is in the SQL.

The SQL
In this example, we see a stitched query, which makes sense if we have multiple facts in the model. A stitched query is essentially a query that attempts to stitch multiple facts together. It uses the relationships that relate the facts to each other as well as the determinants for the conformed, or common, dimensions defined in the model. A stitched query can be identified by two queries with a full outer join. The wrapper query must include a coalesce statement on the conformed dimensions. Note the following problems in the SQL: The query has no coalesce statement. RSUM indicates an attempt to create a valid key.
select D3.COUNTRY as COUNTRY, D2.CITY as CITY, D2.number_of_orders as number_of_orders from (select SALES_BRANCH.CITY as CITY, XCOUNT(ORDER_HEADER.ORDER_NUMBER for SALES_BRANCH.CITY ) as number_of_orders, RSUM(1 at SALES_BRANCH.CITY order by SALES_BRANCH.CITY asc local) as sc from gosales.gosales.dbo.SALES_BRANCH SALES_BRANCH join gosales.gosales.dbo.ORDER_HEADER ORDER_HEADER on (SALES_BRANCH.SALES_BRANCH_CODE = ORDER_HEADER.SALES_BRANCH_CODE) group by SALES_BRANCH.CITY order by CITY asc ) D2 full outer join (select COUNTRY_MULTILINGUAL.COUNTRY as COUNTRY, RSUM(1 at COUNTRY_MULTILINGUAL.COUNTRY order by COUNTRY_MULTILINGUAL.COUNTRY asc local) as sc from gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL group by COUNTRY_MULTILINGUAL.COUNTRY order by COUNTRY asc

User Guide 245

Chapter 8: The SQL Generated by Cognos 8

) D3 on (D2.sc = D3.sc)

By looking at the stitched columns in each query, we see that they are being calculated on unrelated criteria. This explains why there is no apparent relationship between the countries and cities in the report. So why do we see a stitched query? To answer that question, we must look at the model. In this example, the query items used in the report came from different query subjects. Country came from Country Multilingual, City came from Sales Branch, and the Number of Orders came from a count on Order Number in the Order Header query subject.

The problem is that the query splits because the query engine sees this as a multiple-fact query. However, the split does not have a valid key on which to stitch because there is no item that both facts have in common. There is more than one way to solve this problem but both require understanding the data.

Solution 1
You can add a filter to Country Multilingual that changes the cardinality of the relationship to 1-1.
Select * from [GOSL].COUNTRY_MULTILINGUAL Where COUNTRY_MULTILINGUAL."LANGUAGE"=EN

Or you can add a filter on the relationship and change the cardinality to 1-1.
COUNTRY.COUNTRY_CODE = COUNTRY_MULTILINGUAL.COUNTRY_CODE and COUNTRY_MULTILINGUAL.LANGUAGE = EN

Either choice results in a model that has a single fact in this query.

Solution 2
Simplify the model by consolidating the related query subjects. This gives the greatest benefit by simplifying the model and reducing the opportunities for error in query generation.

With either solution, the result of the query is now correct. 246 Framework Manager

Chapter 8: The SQL Generated by Cognos 8

The SQL is no longer a stitched query.

select Country.c7 as COUNTRY, SALES_BRANCH.CITY as CITY, XCOUNT(ORDER_HEADER.ORDER_NUMBER for Country.c7,SALES_BRANCH.CITY ) as number_of_orders from (select COUNTRY.COUNTRY_CODE as c1, COUNTRY_MULTILINGUAL.COUNTRY as c7 from gosales.gosales.dbo.COUNTRY COUNTRY join gosales.gosales.dbo.COUNTRY_MULTILINGUAL COUNTRY_MULTILINGUAL on (COUNTRY.COUNTRY_CODE = COUNTRY_MULTILINGUAL.COUNTRY_CODE) where COUNTRY_MULTILINGUAL.LANGUAGE='EN' ) Country join gosales.gosales.dbo.SALES_BRANCH SALES_BRANCH on (SALES_BRANCH.COUNTRY_CODE = Country.c1) join gosales.gosales.dbo.ORDER_HEADER ORDER_HEADER on (SALES_BRANCH.SALES_BRANCH_CODE = ORDER_HEADER.SALES_BRANCH_CODE) group by Country.c7, SALES_BRANCH.CITY

Resolving Queries That Are Split in the Wrong Place

Sometimes using 1-n cardinality does not resolve circular join paths. Incorrect results are still returned because of an improperly-formed stitched query. For example, the model contains these objects.

User Guide 247

Chapter 8: The SQL Generated by Cognos 8

If you report on Sales Target and Actual Sales grouped by Product and Sales Staff, the result set is incorrect. Actual Sales are a bit too large.

To check the result, query each fact separately.

This confirms that the first report is giving a much larger result for Actual Sales than it should.

The SQL
Note the following problems when you look at the SQL: Only one of the dimension columns has a coalesce statement. This indicates that the query has been improperly split. Grouping is correct for the Sales Target side of the query. This explains why Sales Target is accurate. The quantity side of the stitched query is grouped only by Product, which explains why the Actual Sales are too large.
select coalesce(D2.PRODUCT_NAME,D3.PRODUCT_NAME) as PRODUCT_NAME, D2.LAST_NAME as LAST_NAME, D2.SALES_TARGET as SALES_TARGET, D3.Actual_sales as Actual_sales from (select Product.PRODUCT_NAME as PRODUCT_NAME, SALES_STAFF.LAST_NAME as LAST_NAME, XSUM(SALES_TARGET.SALES_TARGET for Product.PRODUCT_NAME,SALES_STAFF.LAST_NAME ) as SALES_TARGET from

248

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

(select PRODUCT_MULTILINGUAL.PRODUCT_NAME,PRODUCT.PRODUCT_NUMBER from gosales.gosales.dbo.PRODUCT PRODUCT, gosales.gosales.dbo.PRODUCT_MULTILINGUAL PRODUCT_MULTILINGUAL where PRODUCT.PRODUCT_NUMBER = PRODUCT_MULTILINGUAL.PRODUCT_NUMBER) Product join gosales.gosales.dbo.SALES_TARGET SALES_TARGET on (Product.PRODUCT_NUMBER = SALES_TARGET.PRODUCT_NUMBER) join gosales.gosales.dbo.SALES_STAFF SALES_STAFF on (SALES_STAFF.SALES_STAFF_CODE = SALES_TARGET.SALES_STAFF_CODE) group by Product.PRODUCT_NAME, SALES_STAFF.LAST_NAME ) D2 full outer join (select Product.PRODUCT_NAME as PRODUCT_NAME, XSUM(XSUM((ORDER_DETAILS.QUANTITY * ORDER_DETAILS.UNIT_SALE_PRICE) for Product.PRODUCT_NAME ) at Product.PRODUCT_NAME for Product.PRODUCT_NAME ) as Actual_sales from (select PRODUCT_MULTILINGUAL.PRODUCT_NAME,PRODUCT.PRODUCT_NUMBER from gosales.gosales.dbo.PRODUCT PRODUCT, gosales.gosales.dbo.PRODUCT_MULTILINGUAL PRODUCT_MULTILINGUAL where PRODUCT.PRODUCT_NUMBER = PRODUCT_MULTILINGUAL.PRODUCT_NUMBER) Product join gosales.gosales.dbo.ORDER_DETAILS ORDER_DETAILS on (Product.PRODUCT_NUMBER = ORDER_DETAILS.PRODUCT_NUMBER) group by Product.PRODUCT_NAME ) D3 on (D2.PRODUCT_NAME = D3.PRODUCT_NAME)

These problems exist because nothing was selected from Order Header. It was not included in the query so there was no way to link Sales Staff to Order Details. Linking Sales Staff to Order Details was not necessary to connect all the tables because there was already a relationship between Sales Staff and Sales Target. Although you can resolve this by including an item from Order Header in the report, your users may not know to do that. We recommend that you fix it in the model. This is the recommended solution from both a dimensional and business modeling standpoint. In addition, a simpler model makes it harder to write a report that generates bad SQL. Consolidate query subjects where logical groupings are possible. In this example, combine the Order Details and Order Header query subjects. The new group of query subjects can now be used for dimensional modeling.

User Guide 249

Chapter 8: The SQL Generated by Cognos 8

When you use this new group of query subjects, the report looks like this.

When you look at the SQL, you see this:

select coalesce(D2.PRODUCT_NAME,D3.PRODUCT_NAME) as PRODUCT_NAME, coalesce(D2.LAST_NAME,D3.LAST_NAME) as LAST_NAME, D2.SALES_TARGET as SALES_TARGET, D3.Actual_sales as Actual_sales from (select Product.PRODUCT_NAME as PRODUCT_NAME, SALES_STAFF.LAST_NAME as LAST_NAME, XSUM(SALES_TARGET.SALES_TARGET for Product.PRODUCT_NAME,SALES_STAFF.LAST_NAME ) as SALES_TARGET from (select PRODUCT_MULTILINGUAL.PRODUCT_NAME,PRODUCT.PRODUCT_NUMBER from gosales.gosales.dbo.PRODUCT PRODUCT, gosales.gosales.dbo.PRODUCT_MULTILINGUAL PRODUCT_MULTILINGUAL where PRODUCT.PRODUCT_NUMBER = PRODUCT_MULTILINGUAL.PRODUCT_NUMBER) Product join gosales.gosales.dbo.SALES_TARGET SALES_TARGET on (SALES_TARGET.PRODUCT_NUMBER = Product.PRODUCT_NUMBER) join gosales.gosales.dbo.SALES_STAFF SALES_STAFF on (SALES_STAFF.SALES_STAFF_CODE = SALES_TARGET.SALES_STAFF_CODE) group by Product.PRODUCT_NAME, SALES_STAFF.LAST_NAME ) D2 full outer join (select Product.PRODUCT_NAME as PRODUCT_NAME, SALES_STAFF.LAST_NAME as LAST_NAME, XSUM((ORDER_DETAILS_ORDER_HEADER.c5 * ORDER_DETAILS_ORDER_HEADER.c8) for Product.PRODUCT_NAME,SALES_STAFF.LAST_NAME ) as Actual_sales from

250

Framework Manager

Chapter 8: The SQL Generated by Cognos 8

(select PRODUCT_MULTILINGUAL.PRODUCT_NAME,PRODUCT.PRODUCT_NUMBER from gosales.gosales.dbo.PRODUCT PRODUCT, gosales.gosales.dbo.PRODUCT_MULTILINGUAL PRODUCT_MULTILINGUAL where PRODUCT.PRODUCT_NUMBER = PRODUCT_MULTILINGUAL.PRODUCT_NUMBER) Product join (select ORDER_DETAILS.PRODUCT_NUMBER as c4, ORDER_DETAILS.QUANTITY as c5, ORDER_DETAILS.UNIT_SALE_PRICE as c8, ORDER_HEADER.SALES_STAFF_CODE as c14 from gosales.gosales.dbo.ORDER_DETAILS ORDER_DETAILS join gosales.gosales.dbo.ORDER_HEADER ORDER_HEADER on (ORDER_HEADER.ORDER_NUMBER = ORDER_DETAILS.ORDER_NUMBER) ) ORDER_DETAILS_ORDER_HEADER on (ORDER_DETAILS_ORDER_HEADER.c4 = Product.PRODUCT_NUMBER) join gosales.gosales.dbo.SALES_STAFF SALES_STAFF on (SALES_STAFF.SALES_STAFF_CODE = ORDER_DETAILS_ORDER_HEADER.c14) group by Product.PRODUCT_NAME, SALES_STAFF.LAST_NAME ) D3 on ((D2.PRODUCT_NAME = D3.PRODUCT_NAME) and (D2.LAST_NAME = D3.LAST_NAME)))

User Guide 251

Chapter 8: The SQL Generated by Cognos 8

252

Framework Manager

Appendix A: Troubleshooting
This appendix describes some issues that you may need to troubleshoot. For more troubleshooting topics, see the Cognos 8 Troubleshooting Guide.

Expression Syntax for Different Languages

If you import from another Framework Manager project, expression syntax is not adjusted for each language. For example, you create a Framework Manager project using French as the design language and you use French-specific syntax in calculations and filters. You then create a new project using English as the design language and you import the French project into the new project. Expressions defined in the calculations and filters are invalid. The solution is to manually modify the expression after importing.

Long Time to Process an SAP BW Query

When reading an SAP BW Query on top of an Infoset that was built on a MultiProvider, such as InfoCube, ODS, and InfoObject, queries may take a long time to process. The solution is to import the Infoset in a new project and clear the Conformed Dimensions option.

Unable to View the Result Set of a Stored Procedure

If the result set of a stored procedure contains a CLOB (character large object) or BLOB (binary large object), you must modify the stored procedure before running it.

Steps to Use CLOBS

1. Create a model query subject that references the stored procedure. 2. Insert a Cast or Substring function to calculate a string based on the CLOB.

Steps to Use BLOBS

1. Create a model query subject that references the stored procedure. 2. Remove the BLOB from the Select statement of the query subject. 3. Add query items to the Select statement that perform a lookup on the table that contains the BLOB data.

Data Query Stored Procedure Updates the Data Source

You have a stored procedure with its type set to Data Query, which means the stored procedure issues a read-only transaction. When you run the stored procedure in Event Studio, an error message says that the stored procedure wants to update the database. The reason for the error is that the stored procedure contains a passive transaction that is supported by the underlying database. Click OK so that the stored procedure updates the database. No other action is required.

User Guide 253

Appendix A: Troubleshooting

Unable to Execute Stored Procedures Imported from ERWin Metadata Source

If you import a stored procedure from an ERWin metadata source, you are unable to execute it. After you import from the ERWin metadata source, the solution is to reimport the stored procedures directly from the database into Framework Manager.

Unable to Use Preview and Security Filters with Stored Procedure Query Subjects
When you create a stored procedure query subject in Framework Manager, preview and security filters are not supported.

Unable to Use an IQD Created in Framework Manager That Contains an Oracle Stored Procedure
When trying to use an IQD created in Framework Manager that contains an Oracle stored procedure, you may receive a message similar to the following: (TR0118) Transformer can't read the database [datasource] defined in <Lan location>\<datasource><iqd_name>.iqd. DMS-E_General A general exception has occurred during operation 'execute' The native SQL generated in an IQD created in Framework Manager is wrong. The IQD cannot be used in Transformer. To resolve this problem, execute the stored procedure and set the Externalize Method to IQD. Create a model query subject from the executed stored procedure, then publish the package and open in Transformer.

Cannot Test a Query Subject Imported from a Third-party Data Source

You may not be able to test a query subject that you imported from a third-party data source if any of the following conditions exist: The Framework Manager data source object created by the third-party import, and referenced by the query subject, does not have an identically named corresponding data source in the Cognos 8 Business Intelligence content store. The corresponding content store data source exists but is not valid (i.e., the connection information is wrong). The optional schema or catalog properties of the data source object that the third-party import created and the query subject references are incorrect (for the databases accepting case-sensitive identifiers, you should also make sure the case is also right). The database object (such as a table or view) represented by the query subject no longer exists in the database or it was renamed since the third-party model was created, or it is otherwise not accessible within the current connection. For example, you test a query subject and get this error message: QE-DEF-0177 An error occurred while performing operation 'sqlPrepareWithOptions' status='-201'. UDA-SQL-0196 The table or view "GOSALES1.COGNOS.COM.GOSALES.CONVERSION_RATE" was not found in the dictionary.

254

Framework Manager

Appendix A: Troubleshooting As a solution, ensure that none of the conditions enumerated above apply.

Script Error Occurs When Testing Query Subjects

When you test a query subject in Framework Manager, and you do not have the most recent version of Internet Explorer, a script error message appears. It is important to apply all required operating system patches and to use only the versions of third-party software that are supported. Otherwise, your product may not work properly. For an up-to-date list of environments supported by Cognos products, see the Cognos support Website (http://support.cognos.com).

Unable to Validate a Calculation if SQL Was Invalid Earlier

If you create an embedded calculation in a query subject and the calculation contained invalid SQL at some point, you cannot validate the query subject. This happens with data source query subjects and model query subjects. For example, you create an embedded calculation that references a query subject that was not added to the model yet. When the query subject is added to the model, the calculation appears as broken but really is correct. The solution for data source query subjects is to open the Expression Editor for each calculation and click OK in the dialog box to refresh the calculation. The solution for model query subjects is to recreate the calculation.

Joins That Contradict Index and Key Information

Cognos 8 uses unique indexes and primary keys specified in the determinants in Framework Manager. When you import metadata, Framework Manager obtains information from the data source and stores it in the query subject as a determinant. If you create relationships in Framework Manager that use fewer columns than the columns that define one of the unique indexes or the primary key, double-counting may be introduced. This is because the metadata has not defined the granularity for the "one" side of a one-to-many relationship, or for one of the sides of a one-to-one relationship. The generated SQL uses outer joins and subqueries to avoid double-counting. The solution is modify the relationships to use all keyed or indexed columns, or remove determinants that contradict the relationship.

Security Error Messages in Windows 2003 Server Edition

If you are using Windows 2003 Server, an error message may appear that Framework Manager (fm.exe) is not a trusted site and, as a result, Internet Explorer security messages may appear with the OK button disabled. The solution is to add Framework Manager as a trusted site by clicking Add in the error message.

Required Currency Not Shown

If Framework Manager does not show the currency you require in the Currency dialog box, you must ensure that you install the appropriate language packs to support the currency symbols you require. For example, to have the Indian currency symbol (rupee) appear, you must run an operating system or install a language pack that can show this symbol. The Japanese operating system or Japanese language is one example that can show the Indian currency symbol (rupee). User Guide 255

Appendix A: Troubleshooting

Unable to Find Functions List for Vendor

When creating a package, you cannot view the functions list for your data source vendor. Ensure that the functions list was selected.

Steps to Select the Vendor Function List

1. In the Project Viewer, click on the package that you want to update. 2. From the Actions menu, select Package, and click Specify Package Functions List. 3. Check whether the vendor is listed in the Selected function sets box on the right and, if not, add it from the Available function sets box on the left.

Expressions Imported from Business Objects Metadata Source Do Not Work

The calculation, filter, and join expressions that are imported from a Business Objects metadata source do not work in Framework Manager. The reason is that Framework Manager and Business Objects use different paradigms for expression syntax. An example of a Business Objects filter is
@Select(Country\Country) LIKE 'C%'

An example of the same filter in Framework Manager is

[gosales-oracle].[Country].[Country] LIKE 'C%'

Similarly, embedded filters in the Where clause of a query subject do not work. The syntax is imported as
SALESTAFF.SALESTARGET>900000

The same clause in Framework Manager may be

[gosales-oracle].SALESTAFF.SALESTARGET>900000

After importing expressions from Business Objects, the solution is to edit these expressions manually in Framework Manager to conform to the equivalent Framework Manager syntax.

Invalid Role-Based Packages after Upgrading a Model

After upgrading a model, if you double-click the packages folder, you may notice some role-based packages which appear unusable. The packages may not appear in some Object Security dialog boxes. To resolve this problem, you should run Verify Model (Project menu) and repair or delete the invalid role-based packages from the model.

FDS Error Occurs When Using Vendor Specific Functions

You may receive an FDS error while running reports after upgrading to Cognos 8. This error occurs because a function set has not been defined for the data source that you are using. To resolve this problem, define a function set for the data source. 1. Open the model in Framework Manager. 2. In the Project Viewer, click on the data source and click Type in the properties pane. 3. Click on Click to Edit beside Function Set ID and select Set Function list based on the data source type. 4. Under Function Set, select the database type that corresponds to the data source and click OK.

256

Framework Manager

Appendix A: Troubleshooting 5. Save the model and ensure that model versioning is turned off before publishing the package. This will prevent users from having to update their reports.

Columns With the BIT Datatype Are Summarized in Query Studio Reports
Some databases, such as Microsoft SQL Server and Sybase Adaptive Server (Enterprise and IQ), support a BIT datatype. If you have a table that has such a column datatype, Framework Manager imports this column as a two-byte integer. The only summary operation that you can perform on this type of column is count. Framework Manager cannot distinguish these columns from regular two-byte integer columns and will have its associated Usage property set to fact. To avoid automatically summarizing these columns in Query Studio reports, set the Usage property in Framework Manager for BIT columns to attribute.

Error With Some Graphic Items

You are using a model imported from Teradata. When you test some query subjects that contain graphic items, you see this error: QE-DEF-0177 An error occurred while performing operation 'sqlOpenResult' status='-28'. UDA-SQL-0114 The cursor supplied to the operation "sqlOpenResult" is inactive. UDA-SQL-0107 A general exception has occurred during the operation "SgiCursor::doOpenResult()". [NCR][ODBC Teradata Driver][Teradata RDBMS] An unknown character string translation was requested. The reason is that the GRAPHIC and VARGRAPHIC datatypes are not supported. For a complete list of supported datatypes, see the Cognos support Web site (http://support.cognos.com).

Errors Creating Expressions Containing Vendor Specific Functions

If you create expressions using functions that are not supported by your database vendor, you may receive errors. You should only use functions that are supported by your database vendor.

Relationships Involving Table Views Are Not Imported from an Oracle Designer File
Primary key and foreign key relationships involving at least one table view are not imported from an Oracle Designer file into Framework Manager. You must create these relationships manually.

SQL View Definitions Are Not Imported from a Power Designer File
The views in Power Designer must be linked to the table that they reference. Otherwise the information is not saved in the Power Designer file and cannot be imported. See the tooltip for the third-party import bridge for Power Designer.

User Guide 257

Appendix A: Troubleshooting

Undoing Repairs Does Not Reset Prompt Values

When upgrading a ReportNet 1.x model, you enter a prompt value that is not valid. When you undo the repairs made during the verify process, the prompt value is not reset. If you restart the verify process, you are not asked for the prompt value. The solution is to close the model without saving it, reopen it, and start the upgrade process again using the correct prompt value.

258

Framework Manager

Appendix B: Using the Expression Editor

An expression is any combination of operators, constants, functions, and other components that evaluates to a single value. You build expressions to create calculation and filter definitions. A calculation is an expression that you use to create a new value from existing values contained within a data item. A filter is an expression that you use to retrieve a specific subset of records. The Expression Editor shows the expression components that are supported by the data source in which the metadata is stored. For example, if you import metadata from an Oracle data source, the Expression Editor shows only the elements that are supported in Oracle. When creating an expression that will be used in a double-byte environment, such as Japanese, the only special characters that will work are ASCII-7 and ~ || - $ .

Operators
Operators specify what happens to the values on either side of the operator. Operators are similar to functions, in that they manipulate data items and return a result.

(
Inserts an open parenthesis in your expression.

Syntax
(expression)

)
Inserts a closed parenthesis in your expression.

Syntax
(expression)

*
Multiplies two numeric values.

Syntax
value1 * value2

,
Separates expression components.

Syntax
expression(param1, param2)

/
Divides two numeric values.

Syntax
value1 / value2

User Guide 259

Appendix B: Using the Expression Editor

||
Concatenates strings.

Syntax
string1 || string2

+
Adds two values.

Syntax
value1 + value2

Subtracts two numeric values or negates a numeric value.

Syntax
value1 - value2 or - value

<
Compares values against a defined value and retrieves the values that are less than the defined value.

Syntax
value1 < value2

<=
Compares values against a defined value and retrieves the values that are less than or equal to the defined value.

Syntax
value1 <= value2

<>
Compares values against a defined value and retrieves the values that are not equal to the defined value.

Syntax
value1 <> value2

=
Compares values against a defined value and retrieves the values that are equal to the defined value.

Syntax
value1 = value2

>
Compares values against a defined value and retrieves the values that are greater than the defined value.

Syntax
value1 > value2

260

Framework Manager

Appendix B: Using the Expression Editor

->
Used as a separator in a literal member expression.

Syntax
[namespace].[dimension].[hierarchy].[level]->[L1]

>=
Compares values against a defined value and retrieves the values that are greater than or equal to the defined value.

Syntax
value1 >= value2

and
Returns true if the conditions on both sides of the expression are true.

Syntax
arg1 AND arg2

auto
Use with summary expressions to define the scope to be adjusted based on the grouping columns in the query.

Syntax
aggregate_function ( expression AUTO )

between
Determines if a value falls in a given range.

Syntax
name BETWEEN value1 and value2

case
Use with When, Then, Else, and End.

Syntax
CASE expression { WHEN expression THEN expression } [ ELSE expression ] END

contains
Determines if a string contains another string.

Syntax
string1 CONTAINS string2

currentMeasure
Keyword that can be used as the first argument of member summary functions.

Syntax
aggregate_function( currentMeasure within set expression )

distinct
Includes only distinct occurrences within a data item in a calculation.

User Guide 261

Appendix B: Using the Expression Editor

Syntax
DISTINCT dataItem

else
Use with If or Case constructs.

Syntax
IF (condition) THEN .... ELSE (expression) , or CASE .... ELSE expression END

end
Use with Case When construct.

Syntax
CASE .... END

ends with
Determines if a string ends with a given string.

Syntax
string1 ENDS WITH string2

for
Use with summary expressions to define the scope of the aggregation in the query.

Syntax
aggregate_function ( expression FOR expression { , expression } )

for all
Use with summary expressions to define the scope to be all the specified grouping columns in the query. See also FOR clause.

Syntax
aggregate_function ( expression FOR ALL expression { , expression } )

for any
Use with summary expressions to define the scope to be adjusted based on a subset of the grouping columns in the query. Equivalent to FOR clause.

Syntax
aggregate_function ( expression FOR ANY expression { , expression } )

for report
Use with summary expressions to define the scope to be the whole query. See also FOR clause.

Syntax
aggregate_function ( expression FOR REPORT )

if
Use with Then and Else.

Syntax
IF (condition is true) THEN (action) ELSE (alternate action)

262

Framework Manager

Appendix B: Using the Expression Editor

in
Determines if a value exists in a given list of values.

Syntax
exp1 IN (exp_list)

in_range
Determines if an item exists in a given list of constant values or ranges.

Syntax
expression IN_RANGE { constant : constant [ , constant : constant ] }

is missing
Determines if a value is undefined in the data.

Syntax
value IS MISSING

is null
Determines if a value is undefined in the data.

Syntax
value IS NULL

is not missing
Determines if a value is defined in the data.

Syntax
value IS NOT MISSING

is not null
Determines if a value is defined in the data.

Syntax
value IS NOT NULL

like
Determines if a string matches the pattern of another string.

Syntax
string1 LIKE string2

lookup
Finds and replaces data with a value you specify. It is preferable to use the CASE construct.

Syntax
LOOKUP (name) in (value1 --> value2) default (expression)

Example
lookup([Country]) in ('Canada'-->([List Price] * 0.60), 'Australia'-->([List Price] * 0.80)) default([List Price])

not
Returns true if the condition is false, otherwise returns false.

User Guide 263

Appendix B: Using the Expression Editor

Syntax
NOT arg

or
Returns true if either of the two conditions on both sides of the expression is true.

Syntax
arg1 OR arg2

prefilter
Performs a summary calculation before applying the summary filter.

Syntax
summary ([expression] PREFILTER)

rows
Counts the number of rows output by the query. Use with Count().

Syntax
count(ROWS)

starts with
Determines if a string starts with a given string.

Syntax
string1 STARTS WITH string2

then
Use with If or Case constructs.

Syntax
IF (condition) THEN ...., or CASE expression WHEN expression THEN .... END

when
Use with Case construct.

Syntax
CASE [expression] WHEN .... END

Summaries
This list contains predefined functions that return either a single summary value for a group of related values or a different summary value for each instance of a group of related values.

aggregate
Returns a calculated value using the appropriate aggregation function, based on the aggregation type of the expression.

Syntax
aggregate ( expr [ auto ] ) aggregate ( expr for [ all | any ] expr { , expr } ) aggregate ( expr for report )

264

Framework Manager

Appendix B: Using the Expression Editor

average
Returns the average value of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
average ( [ distinct ] expr [ auto ] ) average ( [ distinct ] expr for [ all | any ] expr { , expr } ) average ( [ distinct ] expr for report )

Example
average ( Sales )

Result: The average of all Sales values.

count
Returns the number of selected data items excluding NULL values. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
count ( [ distinct ] expr [ auto ] ) count ( [ distinct ] expr for [ all | any ] expr { , expr } ) count ( [ distinct ] expr for report )

Example
count ( Sales )

Result: The total number of entries under Sales.

maximum
Returns the maximum value of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
maximum ( [ distinct ] expr [ auto ] ) maximum ( [ distinct ] expr for [ all | any ] expr { , expr } ) maximum ( [ distinct ] expr for report )

Example
maximum ( Sales )

Result: The maximum value of all Sales values.

median
Returns the median value of selected data items.

Syntax
median ( expr [ auto ] ) median ( expr for [ all | any ] expr { , expr } ) median ( expr for report )

minimum
Returns the minimum value of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
minimum ( [ distinct ] expr [ auto ] ) minimum ( [ distinct ] expr for [ all | any ] expr { , expr } ) minimum ( [ distinct ] expr for report )

User Guide 265

Appendix B: Using the Expression Editor

Example
minimum ( Sales )

Result: The minimum value of all Sales values.

moving-average
Returns a moving average by row for a specified set of values of over a specified number of rows. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
moving-average ( <for-option> ] [ moving-average ( prefilter ] ) <for-option> ::= numeric_expr , numeric_expr [ at exp {, expr } ] [ prefilter ] ) [ distinct ] numeric_expr , numeric_expr [ <for-option> ] [ for expr {, expr } | for report | auto

Example
moving-average ( Qty, 3 )

Result: For each row, this displays the quantity and a moving average of the current row and the preceding two rows. Qty -----200 700 400 200 200 500 Moving-Average (Qty, 3) -----------------------------------NULL NULL 433.3333 433.3333 266.6667 300.0000

moving-total
Returns a moving total by row for a specified set of values over a specified number of rows. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
moving-total ( numeric_expr , numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) moving-total ( [ distinct ] numeric_expr , numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
moving-total ( Quantity, 3 )

266

Framework Manager

Appendix B: Using the Expression Editor Result: For each row, this displays the quantity and a moving total of the current row and the preceding two rows. Qty -----200 700 400 200 200 500 Moving-Total (Qty, 3) -------------------------------NULL NULL 1300 1300 800 900

percentage
Returns the percent of the total value for selected data items. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
percentage ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) percentage ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
percentage ( sales 98 )

Result: Shows the percentage of the total sales for 1998 that is attributed to each sales representative. Sales Rep -------------------Bill Gibbons Bjorn Flertjan Chris Cornel Sales 98 -------------60646 62523 22396 Percentage -----------------7.11% 7.35% 2.63%

percentile
Returns a value, on a scale of one hundred, that indicates the percent of a distribution that is equal to or below the selected data items. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
percentile ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) percentile ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
percentile ( Sales 98 )

User Guide 267

Appendix B: Using the Expression Editor Result: For each row, displays the percentage of rows that are equal to or less than the quantity value of that row. Qty -----800 700 600 500 400 400 200 200 Percentile (Qty) ----------------1 0.875 0.75 0.625 0.5 0.5 0.25 0.25

quantile
Returns the rank of a value in terms of a range that you specify. It returns integers to represent any range of ranks, such as 1 (highest) to 100 (lowest). The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
quantile ( numeric_expr, numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) quantile ( [ distinct ] numeric_expr, numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
quantile ( Qty, 4 )

Result: The quantity, the rank of the quantity value, and the quantity values broken down into 4 quantile groups (quartiles). Qty -----800 700 600 500 400 400 200 200 Rank (Qty) ----------------1 2 3 4 5 5 7 7 Quantile (Qty, 4) ----------------------1 1 2 2 3 3 4 4

quartile
Returns the rank of a value, represented as integers from 1 (highest) to 4 (lowest), relative to a group of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

268

Framework Manager

Appendix B: Using the Expression Editor

Syntax
quartile ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) quartile ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
quartile ( Qty )

Result: This displays the quantity and the quartile of the quantity value represented as integers from 1 (highest) to 4 (lowest). Qty -----450 400 350 300 250 200 150 100 Quartile (Qty) --------------------1 1 2 2 3 3 4 4

rank
Returns the rank value of selected data items. If two or more rows tie, then there is a gap in the sequence of ranked values (also known as Olympic ranking). The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
rank ( expr [sort_order] {, expr [sort_order] } [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) rank ( [ distinct ] expr [sort_order] {, expr [sort_order] } [ <for-option>] prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto [

Example
rank ( Sales 98 )

Result: For each row, this displays the rank value of sales for 1998 that is attributed to each sales representative, and skips some numbers when there is a tie between rows. Sales Rep ---------------Bill Gibbons Bjorn Flertjan Chris Cornel John Smith Sales 98 ----------60000 50000 50000 48000 Rank -----------1 2 2 4

User Guide 269

Appendix B: Using the Expression Editor

running-average
Returns the running average by row (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-average ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-average ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-average ( Qty )

Result: For each row, this displays the quantity and a running average of the current and the previous rows. Name ------Smith Smith Smith Smith Wong Wong Qty -----7 3 6 4 3 5 Avg -----5 5 5 5 4 4 Running-Average for name -------------------------------------7 5 5.33 5 3 4

running-count
Returns the running count by row (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-count ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-count ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-count ( Qty )

Result: For each row, this displays the quantity and a running count of the position of current row. Name ------Smith Smith Smith Smith Wong Wong Qty -----7 3 6 4 3 5 Count --------4 4 4 4 3 3 Running-Count for name -------------------------------------1 2 3 4 1 2

270

Framework Manager

Appendix B: Using the Expression Editor

running-difference
Returns a running difference by row, calculated as the difference between the value for the current row and the preceding row, (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-difference ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-difference ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-difference ( Qty )

Result: For each row, this displays the quantity and a running difference between the value for the current row and the preceding row. Name ------Smith Smith Smith Smith Wong Wong Qty -----7 3 6 4 3 5 Running-Difference for name -------------------------------------NULL -4 3 -2 -1 2

running-maximum
Returns the running maximum by row (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-maximum ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-maximum ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-maximum ( Qty )

User Guide 271

Appendix B: Using the Expression Editor Result: For each row, this displays the quantity and a running maximum of the current and previous rows. Name ------Smith Smith Smith Smith Wong Wong Qty -----2 3 6 7 3 5 Max -----7 7 7 7 5 5 Running-Maximum (Qty) for name -------------------------------------2 3 6 7 3 5

running-minimum
Returns the running minimum by row (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-minimum ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-minimum ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-minimum ( Qty )

Result: For each row, this displays the quantity and a running minimum of the current and previous rows. Name ------Smith Smith Smith Smith Wong Wong Qty ----7 3 6 2 4 5 Min -----2 2 2 2 3 3 Running-Minimum (Qty) for name -------------------------------------7 3 3 2 4 4

running-total
Returns a running total by row (including the current row) for a set of values. The <for-option> defines the scope of the function. The at option defines the level of aggregation and can only be used in the context of relational datasources. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
running-total ( numeric_expr [ at exp {, expr } ] [ <for-option> ] [ prefilter ] ) running-total ( [ distinct ] numeric_expr [ <for-option> ] [ prefilter ] ) <for-option> ::= for expr {, expr } | for report | auto

Example
running-total ( Qty )

272

Framework Manager

Appendix B: Using the Expression Editor Result: For each row, this displays the quantity and a running total of the current and previous rows. Name ------Smith Smith Smith Smith Wong Wong Qty -----2 3 6 7 3 5 Total -------18 18 18 18 12 12 Running-Total (Qty) for name -------------------------------------2 5 11 18 3 8

standard-deviation
Returns the standard deviation of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
standard-deviation ( [ distinct ] expr [ auto ] ) standard-deviation ( [ distinct ] expr for [ all | any ] expr { , expr } ) standard-deviation ( [ distinct ] expr for report )

Example
standard-deviation ( ProductCost )

Result: A value indicating the deviation between product costs and the average product cost.

standard-deviation-pop
Computes the population standard deviation and returns the square root of the population variance. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
standard-deviation-pop ( [ distinct ] expr [ auto ] ) standard-deviation-pop ( [ distinct ] expr for [ all | any ] expr { , expr } ) standard-deviation-pop ( [ distinct ] expr for report )

Example
standard-deviation-pop ( ProductCost )

Result: A value of the square root of the population variance.

total
Returns the total value of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
total ( [ distinct ] expr [ auto ] ) total ( [ distinct ] expr for [ all | any ] expr { , expr } ) total ( [ distinct ] expr for report )

Example
total ( Sales )

Result: The total value of all Sales values.

User Guide 273

Appendix B: Using the Expression Editor

variance
Returns the variance of selected data items. The keyword distinct is available for backward compatibility of expressions used in previous versions of the product.

Syntax
variance ( [ distinct ] expr [ auto ] ) variance ( [ distinct ] expr for [ all | any ] expr { , expr } ) variance ( [ distinct ] expr for report )

Example
variance ( Product Cost )

Result: A value indicating how widely product costs vary from the average product cost.

variance-pop
Returns the population variance of a set of numbers after discarding the nulls in this set.

Syntax
variance-pop ( [ distinct ] expr [ auto ] ) variance-pop ( [ distinct ] expr for [ all | any ] expr { , expr } ) variance-pop ( [ distinct ] expr for report )

Example
variance-pop ( Qty)

Result: For each row, this displays the population variance of a set of numbers after discarding the nulls in this set.

Constants
A constant is a fixed value that you can use in an expression.

date
Inserts the current system date.

date-time
Inserts the current system date and time.

time with time zone

Inserts a zero time with time zone.

timestamp with time zone

Inserts an example of a timestamp with time zone.

interval
Inserts a zero interval.

interval year
Inserts a zero year interval.

interval month
Inserts a zero month interval.

interval year to month

Inserts a zero year to month interval. 274 Framework Manager

Appendix B: Using the Expression Editor

interval day
Inserts a zero day interval.

interval hour
Inserts a zero hour interval.

interval minute
Inserts a zero minute interval.

interval second
Inserts a zero second interval.

interval day to hour

Inserts a zero day to hour interval.

interval day to minute

Inserts a zero day to minute interval.

interval day to second

Inserts a zero day to second interval.

interval hour to minute

Inserts a zero hour to minute interval.

interval hour to second

Inserts a zero hour to second interval.

interval minute to second

Inserts a zero minute to second interval.

null
Inserts a null value if the expression conditions are not met.

number
Inserts the number 0, which you can replace with a new numeric value.

string
Inserts an empty string.

time
Inserts the current system time.

Constructs
if then else Syntax
IF ([Country] = 'Canada') THEN ([List Price] * 0.60) ELSE ([List Price])

User Guide 275

Appendix B: Using the Expression Editor

in_range
Specify one or more constants or ranges. A range can be open ended.

Example
[gosales].[CONVERSIONRATE].[COUNTRYCODE] IN_RANGE { :30 , 40, 50, 999: }

search case Syntax

CASE WHEN [Country] = 'Canada' THEN ([List Price] * 0.60) WHEN [CountryCode] > 100 THEN [List Price] * 0.80 ELSE [List Price] END

simple case Syntax

CASE [Country] WHEN 'Canada' THEN ([List Price] * 0.60) WHEN 'Australia' THEN [List Price] * 0.80 ELSE [List Price] END

Business Date/Time Functions

This list contains business functions for performing date and time calculations.

_add_days
Returns the date or datetime dependent on the first argument resulting from adding integer_exp days to date_exp.

Syntax
_add_days ( date_exp, integer_exp )

Example 1
_add_days ( 2002-04-30 , 1 )

Result: 2002-05-01

Example 2
_add_days ( 2002-04-30 12:10:10.000, 1 )

Result: 2002-05-01 12:10:10.000

_add_months
Returns the date or datetime dependent on the first argument resulting from adding integer_exp months to date_exp.

Syntax
_add_months ( date_exp, integer_exp )

Example 1
_add_months ( 2002-04-30 , 1 )

Result: 2002-05-30

Example 2
_add_months ( 2002-04-30 12:10:10.000, 1 )

276

Framework Manager

Appendix B: Using the Expression Editor Result: 2002-05-30 12:10:10.000

_add_years
Returns the date or datetime dependent on the first argument resulting from adding integer_exp years to date_exp.

Syntax
_add_years ( date_exp, integer_exp )

Example 1
_add_years ( 2002-04-30 , 1 )

Result: 2003-04-30

Example 2
_add_years ( 2002-04-30 12:10:10.000 , 1 )

Result: 2003-04-30 12:10:10.000

_age
Returns a number that is obtained from subtracting date_exp from todays date. This value has the form YYYYMMDD, where YYYY represents the number of years, MM represents the number of months, and DD represents the number of days.

Syntax
_age (date_exp )

Example
Today's date=2003-02-05 _age ( 1990-04-30 )

Result: 120906 that is 12 years, 9 months and 6 days

_day_of_week
Returns the day of week ( between 1 and 7), where 1 is the first day of the week as indicated by the second parameter(between 1 and 7, 1 being Monday and 7 being Sunday). Note that in ISO 8601 standard, a week begins with Monday being day 1. In North America where Sunday is the first day of the week being day 7.

Syntax
_day_of_week ( date_exp, integer )

Example
_day_of_week ( 2003-01-01, 1 )

Result: 3

_day_of_year
Returns the ordinal for the day of the year in date_ exp (1 to 366). Also known as Julian day.

Syntax
_day_of_year ( date_exp )

Example
_day_of_year ( 2003-03-01 )

Result: 61

_days_between
Returns a positive or negative number representing the number of days between the two date expressions. If date_exp1 < date_exp2 then the result will be a negative number. User Guide 277

Appendix B: Using the Expression Editor

Syntax
_days_between ( date_exp1, date_exp2 )

Example
_days_between ( 2002-04-30 , 2002-06-21 )

Result: -52

_days_to_end_of_month
Returns a number representing the number of days remaining in the month represented by the date expression date_exp.

Syntax
_days_to_end_of_month ( date_exp )

Example
_days_to_end_of_month ( 2002-04-20 14:30:22.123 )

Result: 10

_first_of_month
Returns a date or datetime dependent on the argument obtained from converting date_exp to a date with the same year and month but the day set to 1.

Syntax
_first_of_month ( date_exp )

Example 1
_first_of_month ( 2002-04-20 )

Result: 2002-04-01

Example 2
_first_of_month ( 2002-04-20 12:10:10.000 )

Result: 2002-04-01 12:10:10.000

_last_of_month
Returns a date or datetime dependent on the argument that is the last day of the month represented by date_exp.

Syntax
_last_of_month ( date_exp )

Example 1
_last_of_month ( 2002-01-14 )

Result: 2002-01-31

Example 2
_last_of_month ( 2002-01-14 12:10:10.000 )

Result: 2002-01-31 12:10:10.000

_make_timestamp
Returns a timestamp constructed from integer_exp1 (the year), integer_exp2 (the month) and integer_exp3 (the day).

Syntax
_make_timestamp ( integer_exp1, integer_exp2, integer_exp3 )

278

Framework Manager

Appendix B: Using the Expression Editor

Example
_make_timestamp ( 2002 , 01 , 14 )

Result: 2002-01-14 00:00:00.000

_months_between
Returns a positive or negative integer number representing the number of months between date_exp1 to date_exp2. If date_exp1 < date_exp2, then a negative number is returned.

Syntax
_months_between ( date_exp1, date_exp2 )

Example
_months_between ( 2002-01-30, 2002-04-03 )

Result: 2

_week_of_year
Returns the number of the week of the year of the date_exp according to ISO 8601, in which week 1 of the year is the first week of the year to contain a Thursday, which is equivalent to the first week containing January 4th.

Syntax
_week_of_year ( date_exp )

Example
_week_of_year ( 2003-01-01 )

Result: 1

_years_between
Returns a positive or negative integer number representing the number of years from date_exp1 to date_exp2. If date_exp1 < date_exp2 then a negative value is returned.

Syntax
_years_between ( date_exp1, date_exp2 )

Example
_years_between ( 2003-01-30, 2001-04-03 )

Result: 1

_ymdint_between
Returns a number representing the difference between the date expressions date_exp1 and date_exp2. This value has the form YYYYMMDD, where YYYY represents the number of years, MM represents the number of months, and DD represents the number of days.

Syntax
_ymdint_between ( date_exp1, date_exp2 )

Example
_ymdint_between ( 1990-04-30 , 2003-02-05 )

Result: 120906 that is 12 years, 9 months and 6 days

Block Functions
This list contains functions used to access members of a set, usually in the context of PowerPlay Studio. User Guide 279

Appendix B: Using the Expression Editor

_firstFromSet
Returns the first members found in the set up to numeric_exp_max + numeric_exp_overflow. If numeric_exp_max + numeric_exp_overflow is exceeded, then only the max number of members are returned.

Syntax
_firstFromSet ( set_exp, numeric_exp_max , numeric_exp_overflow )

_remainderSet
The member expression will be included in the returned set when the size of the set_exp set is greater than numeric_exp.

Syntax
_remainderSet (member_exp, set_exp , numeric_exp )

Macro Functions
This list contains functions that can be used within a macro. A macro may contain one or more macro functions. A macro is delimited by a number sign (#) at the beginning and at the end. Everything between the number signs is treated as a macro expression, which is executed at run time.

sb
Surround the passed string with square brackets.

Syntax
sb ( string_exp )

Example
#sb ( 'abc' )#

Result: [abc]

sq
Surround the passed string with single quotes.

Syntax
sq ( string_exp )

Example
#sq ( 'zero' )#

Result: 'zero'

dq
Surround the passed string with double quotes.

Syntax
sq ( string_exp )

Example
#sq ( 'zero' )#

Result: "zero"

280

Framework Manager

Appendix B: Using the Expression Editor

CSVIdentityName
Use the identity information of the current authenticated user to lookup values in the specified parameter map. Each individual piece of the user's identity (account name, group names, role names) is used as a key into the map. The unique list of values that is retrieved from the map is then returned as a string, where each value is surrounded by single quotes and where multiple values are separated by commas.

Syntax
CSVIdentityName ( %parameter_map_name [ , separator_string ] )

Example
#CSVIdentityName ( %security_clearance_level_map )#

Result: 'level_500' , 'level_501' , 'level_700'

CSVIdentityNameList
Returns the pieces of the user's identity (account name, group names, role names) as a list of strings. The unique list of values is returned as a string, where each value is surrounded by single quotes and where multiple values are separated by commas.

Syntax
CSVIdentityNameList ( [ separator_string ] )

Example
#CSVIdentityNameList ( )#

Result: 'Everyone' , 'Report Administrators' , 'Query User'

CAMPassport
Returns the passport.

Syntax
CAMPassport ( )

Example
#CAMPassport ( )#

Result: 111:98812d62-4fd4-037b-4354-26414cf7ebef:3677162321

CAMIDList
Returns the pieces of the user's identity (account name, group names, role names) as a list of values separated by commas.

Syntax
CAMIDList ( [ separator_string ] )

Example
#CAMIDList ( )#

Result: CAMID("::Everyone"), CAMID(":Authors"), CAMID(":Query Users"), CAMID(":Consumers"), CAMID(":Metrics Authors")

+
Concatenates two strings.

Syntax
value1 + value2

User Guide 281

Appendix B: Using the Expression Editor

Example
# '{' + $runLocale + '}'#

Result: {en-us}

prompt
Prompt the user for a single value. Only the prompt_name argument is required.

Syntax
prompt ( prompt_name , datatype , defaultText , text , queryItem , trailing_text )

Example
select . . . where COUNTRY_MULTILINGUAL.COUNTRY_CODE CountryCode', 'integer', > #prompt('Starting '10' )#

Result: select . . . where COUNTRY_MULTILINGUAL.COUNTRY_CODE > 150

promptmany
Prompt the user for one or more values. Only the prompt_name argument is required.

Syntax
promptmany ( prompt_name , datatype , defaultText , text , queryItem , trailing_text )

Example
select . . . where COUNTRY_MULTILINGUAL.COUNTRY IN ( #promptmany ( 'CountryName' ) # )

Result: select . . . where COUNTRY_MULTILINGUAL.COUNTRY_CODE IN ('Canada' , 'The Netherlands' , 'Russia')

Common Functions
A-C
abs
Returns the absolute value of numeric_exp. The sign of negative values is changed to positive.

Syntax
abs ( numeric_exp )

Example 1
abs ( 15 )

Result: 15

Example 2
abs ( -15 )

Result: 15

ancestor
Returns the ancestor of the specified member at either the specified (named) level or the specified number of levels above the member. Note: The result is not guaranteed to be consistent when there is more than one such ancestor.

282

Framework Manager

Appendix B: Using the Expression Editor

Syntax
ancestor ( member, level | integer )

ancestors
Returns all the ancestors of a member at a specified level, or distance above the member. (Most data sources support only one ancestor at a specified level, but some support more than one. Hence the result is a member set.)

Syntax
ancestors ( member , level | index )

bottomCount
This function sorts a set according to the value of "numeric_expression" evaluated at each of the members of "set_exp", and returns the bottom "index_exp" members.

Syntax
bottomCount ( set_exp , numeric_exp1 , numeric_exp2 )

bottomPercent
This function is similar to bottomSum, but the threshold is "numeric_exp1" percent of the total.

Syntax
bottomPercent ( set_exp , numeric_exp1 , numeric_exp2 )

bottomSum
This function sorts on "numeric_exp2", evaluated at the corresponding member of "set_exp", and picks up the bottommost elements whose cumulative total is at least numeric_exp1.

Syntax
bottomSum ( set_exp , numeric_exp1 , numeric_exp2 )

cast
Converts an expression to a specified data type. Some data types allow for a length and precision to be specified. Make sure that the target is of the appropriate type and size.

Syntax
cast ( expression, datatype_specification )

Example 1
cast ( '123' , integer )

Result: 123

Example 2
cast ( 12345 , VARCHAR ( 10 ) )

Result: a string containing 12345

Notes
You can specify the following datatypes: CHARACTER, VARCHAR, CHAR, NUMERIC, DECIMAL, INTEGER, SMALLINT, REAL, FLOAT, DATE, TIME, TIMESTAMP, TIME WITH TIME ZONE, TIMESTAMP WITH TIME ZONE, and INTERVAL. When you convert a value of type TIMESTAMP to type DATE, the time portion of the timestamp value is ignored. When you convert a value of type TIMESTAMP to type TIME, the date portion of the timestamp is ignored.

User Guide 283

Appendix B: Using the Expression Editor When you convert a value of type DATE to type TIMESTAMP, the time components of the timestamp are set to zero. When you convert a value of type TIME to type TIMESTAMP, the date component is set to the current system date. When you type cast to an INTERVAL type, you must specify one of the following interval qualifiers: YEAR, MONTH, YEAR TO MONTH, DAY, HOUR, MINUTE, SECOND, DAY TO HOUR, DAY TO MINUTE, DAY TO SECOND, HOUR TO MINUTE, HOUR TO SECOND. Note that you can specify the number of digits for the leading qualifier only, i.e. YEAR(4) TO MONTH, DAY(5). Errors will be reported if the target type and size are not compatible with the source type and size.

ceiling
Returns the smallest integer greater than or equal to numeric_exp.

Syntax
ceiling ( numeric_exp )

Example 1
ceiling ( 4.22 )

Result: 5

Example 2
ceiling ( -1.23 )

Result: -1

character_length
Returns the number of characters in string_exp.

Syntax
character_length ( string_exp )

Example
character_length ( 'Canada' )

Result: 6

children
Returns the set of children of a specified member.

Syntax
children ( member )

coalesce
Returns the first non-null argument (or null if all arguments are null). The Coalesce function takes two or more arguments.

Syntax
coalesce ( exp_list )

completeTuple
Similar to "tuple", identifies a cell location (intersection) based on the specified members, each of which must be from a different dimension. However, completeTuple implicitly includes the default member from all dimensions not otherwise specified in the arguments, rather than the current member. The value of this cell can be obtained with the "value" function.

284

Framework Manager

Appendix B: Using the Expression Editor

Syntax
completeTuple ( member { , member } )

closingPeriod
Returns the last sibling among the descendants of a member at a specified level. Typically used with a time dimension.

Syntax
closingPeriod ( level [, member ] )

cousin
Returns the child member of member2 with the same relative position as the member1 is under its parent.

Syntax
cousin ( member1 , member2 )

current_date
Returns a date value representing the current date of the computer that the database software runs on.

Syntax
current_date

Example
current_date

Result: 2003-03-04

currentMember
Returns the current member of the hierarchy during an iteration. If the specified hierarchy is not present in the context in which the expression is being evaluated, its default member is assumed.

Syntax
currentMember ( hierarchy )

current_time
Returns a time with time zone value, representing the current time of the computer that runs the database software.

Syntax
current_time

Example
current_time

Result: 16:33:11+05:00

current_timestamp
Returns a datetime with time zone value, representing the current timestamp of the computer that runs the database software.

Syntax
current_timestamp

Example
current_timestamp

User Guide 285

Appendix B: Using the Expression Editor Result: 2003-03-03 16:40:15.535000+05:00

D-G
defaultMember
Returns the default member of a hierarchy.

Syntax
defaultMember ( hierarchy )

descendants
Returns the set of descendants a set of members at a specified level or distance from the root, with the option of including or excluding descendants in other levels. Duplicates will be removed from the set.

Syntax
descendants ( set_expr , level | index [ , { self | before | beforewithmember | after }* ] )

distinct
Removes all duplicates from the specified set. The remaining members retain their original order.

Syntax
distinct ( set_expr )

emptySet
Returns an empty member set for the specified hierarchy.

Syntax
emptySet ( hierarchy )

except
Returns the members of "set_exp1" that are not also in "set_exp2". Duplicates are retained only if the optional keyword ALL is supplied as the third argument.

Syntax
except ( set_exp1 , set_exp2 [,ALL] )

exp
Returns e raised to the power of numeric_exp. The constant e is the base of the natural logarithm. See also log.

Syntax
exp ( numeric_exp )

Example
exp ( 2 )

Result: 7.389056

extract
Returns an integer representing the value of datepart (year, month, day, hour, minute, second) in datetime_exp.

Syntax
extract ( datepart , datetime_exp )

286

Framework Manager

Appendix B: Using the Expression Editor

Example 1
extract ( year , 2003-03-03 16:40:15.535 )

Result: 2003

Example 2
extract ( hour , 2003-03-03 16:40:15.535 )

Result: 16

filter
Returns the set resulting from filtering a specified set based on the boolean condition. Each member is included in the result if and only if the corresponding value of "boolean_exp" is true.

Syntax
filter ( set_exp , boolean_exp )

firstChild
Returns the first child of a member.

Syntax
firstChild ( member)

firstSibling
Returns the first child of the parent of a member.

Syntax
firstSibling ( member )

floor
Returns the largest integer less than or equal to numeric_exp.

Syntax
floor ( numeric_exp )

Example 1
floor ( 3.22 )

Result: 3

Example 2
floor ( -1.23 )

Result: -2

generate
This function evaluates "set_exp2" for each member of "set_exp1" and joins the resulting sets by union. If ALL is specified, duplicates in the result are retained.

Syntax
generate ( set_exp1 , set_exp2 [ , ALL ] )

H-L
head
Returns the first "index_exp" elements of "set_exp". The default for "index_exp" is 1.

User Guide 287

Appendix B: Using the Expression Editor

Syntax
head ( set_exp [ , index_exp ] )

hierarchize
This function orders the members of a set in a hierarchy. Members in a level are sorted in their natural order, which is the default ordering of the members along a dimension when no other sort conditions are specified.

Syntax
hierarchize ( set_exp )

hierarchy
Returns the hierarchy that contains the specified level, member or member set.

Syntax
hierarchy ( level | member | set_exp )

ln
Returns the natural logarithm of the numeric_exp.

Syntax
ln ( numeric_exp )

Example
ln ( 4 )

Result: 1.38629

intersect
Returns the intersection of two input sets. The result retains duplicates only when the optional keyword ALL is supplied as the third argument.

Syntax
intersect ( set_exp1 , set_exp2 [ , ALL ] )

H-L
isEmpty
Returns TRUE if the evaluated expression is NULL; FALSE otherwise.

Syntax
isEmpty ( value_exp )

item
Returns a member from a specified location within a set. The index into the set is zero based

Syntax
item ( set_exp , index )

lag
Returns the sibling member that is a specified number of positions prior to a specified member.

Syntax
lag ( member , index_exp )

288

Framework Manager

Appendix B: Using the Expression Editor

lastChild
Returns the last child of a specified member.

Syntax
lastChild ( member )

lastPeriods
Returns the set of members from the same level that ends with the specified member. The number of members returned is the absolute value of "integer_exp". If "integer_exp" is negative, members following and including the specified member are returned. Typically used with a time dimension.

Syntax
lastPeriods ( integer_exp , member )

lastSibling
Returns the last child of the parent of a specified member.

Syntax
lastSibling ( member )

lead
Returns the sibling member that is a specified number of positions following a specified member.

Syntax
lead ( member , index_exp )

level
Returns the level of a member.

Syntax
level ( member )

levels
Returns the level in the hierarchy whose distance from the root is specified by "index".

Syntax
levels ( hierarchy , index )

localtime
Returns a time value, representing the current time of the computer that runs the database software.

Syntax
localtime

Example
localtime

Result: 16:33:11

localtimestamp
Returns a datetime value, representing the current timestamp of the computer that runs the database software.

User Guide 289

Appendix B: Using the Expression Editor

Syntax
localtimestamp

Example
localtimestamp

Result: 2003-03-03 16:40:15.535000

lower
Returns string_exp with all uppercase characters shifted to lowercase.

Syntax
lower ( string_exp )

Example
lower ( 'ABCDEF' )

Result: 'abcdef'

M-Q
member
Defines a member based on the specified expression in the specified hierarchy. "string1" is used to identify the member created by this function it must be unique in the query, and must be different from any other member in the same hierarchy. "string2" is used as the caption of the member; if it is absent, the caption is empty. If the hierarchy is omitted, the measure dimension is assumed. Note: All calculations used as grouping items whose sibling items are other calculations or member sets, should be explicitly assigned to a hierarchy using this function, otherwise the results are not predictable. The only exception to this is where the calculation involves only members of the same hierarchy as the siblings. In that case the calculation is assumed to belong to that hierarchy.

Syntax
member ( value_exp [ , string1 [ , string2 [ , hierarchy ] ] ] )

members
Returns the set of members in a hierarchy or level. In the case of a hierarchy, the order of the members in the result is not guaranteed; if a predictable order is required, an explicit ordering function (such as hierarchize) must be used.

Syntax
members ( hierarchy | level )

mod
Returns the remainder (modulus) of integer_exp1 divided by integer_exp2. The integer_exp2 must not be zero or an exception condition is raised.

Syntax
mod ( integer_exp1, integer_exp2 )

Example
mod ( 20 , 3 )

Result: 2

nestedSet
Returns the set of members of set_expr2 evaluated in the context of the current member of set_expr1. 290 Framework Manager

Appendix B: Using the Expression Editor

Syntax
nestedSet ( set_expr1 , set_expr2 )

nextMember
Returns the next member in the level to which the specified member exists.

Syntax
nextMember ( member )

octet_length
Returns the number of bytes in string_exp.

Syntax
octet_length ( string_exp )

Example 1
octet_length ( 'ABCDEF' )

Result: 6

Example 2
octet_length ( '' )

Result: 0

openingPeriod
Returns the first sibling member among the descendants of a member at a specified level. Typically used with a time dimension.

Syntax
openingPeriod ( level [ , member ] )

order
Arranges members of a specified set, as determined from the set of values created by evaluating "value_exp" for each value of the set, and modified by the third parameter. There are two varieties of order: hierarchized (ASC or DESC) and non-hierarchized (BASC or BDESC, where B stands for "break hierarchy"). The hierarchized ordering first arranges members according to their position in the hierarchy. Then it orders the children of each member according to "value_exp". The non-hierarchized ordering arranges members in the set without regard to the hierarchy. In the absence of an explicit specification, ASC is the default.

Syntax
order ( set_exp , value_exp [ , ASC | DESC | BASC | BDESC ] )

ordinal
Returns the zero-based ordinal value (distance from the root level) of the specified level.

Syntax
ordinal ( level )

parallelPeriod
Returns a member from a different period in the same relative position as a specified member. This function is similar to the "Cousin" function, but is more closely related to time series. It takes the ancestor of "member" at "level" (call it "ancestor"); then it takes the sibling of "ancestor" that is offset (follows) by "int exp" positions, and returns the descendants of that sibling in the same relative position as the specified member as under "ancestor".

User Guide 291

Appendix B: Using the Expression Editor

Syntax
parallelPeriod ( level , int_exp , member )

parent
Returns the member that is the parent of the specified member.

Syntax
parent ( member )

periodsToDate
Returns a set of sibling members from the same level as a given member, as constrained by a specified level. It locates the ancestor of "member" at "level", and returns that ancestor's descendants at the same level as "member", up to and including "member". Typically used with a time dimension.

Syntax
periodsToDate ( level , member )

position
Returns integer value representing the position of the first string_exp in the second string_exp or 0 when the first string_exp is not found.

Syntax
position ( string_exp , string_exp )

Example 1
position ( 'C' , 'ABCDEF' )

Result: 3

Example 2
position ( 'H' , 'ABCDEF' )

Result: 0

power
Returns numeric_exp1 raised to the power numeric_exp2. If numeric_exp1 is negative then numeric_exp2 must result in an integer value.

Syntax
power ( numeric_exp1, numeric_exp2 )

Example
power ( 3 , 2 )

Result: 9

prevMember
Returns the member that immediately precedes the specified member in the same level.

Syntax
prevMember ( member )

292

Framework Manager

Appendix B: Using the Expression Editor

R-Z
roleValue
Returns the value of the attribute that is associated with the role whose name is specified by "string" within the specified context. The second argument is optional only in a number of limited circumstances, where it can be derived from other context. Applications can be made portable across different data sources and models by accessing attributes by role, rather than by query item ID. (For dimensionally modelled relational data sources, assignment of roles is the modeller's responsibility.) Intrinsic roles that are defined for members of all data source types include: _businessKey, _memberCaption, _memberDescription, _memberUniqueName.

Syntax
roleValue ( string [ , member | set_exp ] )

rootMembers
Returns the root members of a hierarchy.

Syntax
rootMembers ( hierarchy )

_round
Returns the numeric expression rounded to the integer_exp places right of the decimal point. NOTE: integer_exp MUST be a non-negative integer.

Syntax
_round ( numeric_exp, integer_exp )

Example
_round ( 1220.42369, 2 )

Result: 1220.42

set
Returns a list of members belonging to the same hierarchy

Syntax
set ( member { , member } )

siblings
Returns the children of the parent of the specified member.

Syntax
siblings ( member )

sqrt
Returns the square root of numeric_exp. numeric_exp must be non-negative.

Syntax
sqrt ( numeric_exp )

Example
sqrt ( 9 )

Result: 3

User Guide 293

Appendix B: Using the Expression Editor

subset
Returns a subset of members from a specified set starting "index_exp1" from the beginning. If the count "index_exp2" is specified, that many members (if available) are returned. Otherwise, all remaining members are returned.

Syntax
subset ( set_exp, index_exp1 [ , index_exp2 ] )

substring
Returns the substring of string_exp that starts at position integer_exp1 for integer_exp2 characters or to the end of string_exp if integer_exp2 is omitted. The first character in string_exp is at position 1.

Syntax
substring ( string_exp , integer_exp1 [ , integer_exp2 ] )

Example
substring ( 'abdefg', 3, 2)

Result: 'de'

tail
Returns the last "index_exp" elements of "set exp". The default for "index_exp" is 1.

Syntax
tail ( set_exp [ , index_exp ] )

topCount
This function sorts a set according to the values of "numeric_exp" evaluated at each of the members of "set_exp", and returns the top "index_exp" members.

Syntax
topCount ( set_exp , index_exp , numeric_exp )

topPercent
This function is similar to topSum, but the threshold is "numeric_exp1" percent of the total.

Syntax
topPercent ( set_exp , numeric_exp1, numeric_exp2 )

topSum
This function sorts on "numeric_exp2", evaluated at the corresponding members of "set_exp", and picks up the topmost elements whose cumulative total is at least "numeric_exp1".

Syntax
topSum ( set_exp , numeric_exp1 , numeric_exp2 )

trim
Returns a string_exp trimmed of leading and\or trailing blanks or trimmed of a certain character specified in match_character_exp. BOTH is implicit when first argument is not stated and blank is implicit when second argument is not stated.

Syntax
trim ( [ [ TRAILING | LEADING | BOTH ] [ match_character_exp ] , ] string_exp )

294

Framework Manager

Appendix B: Using the Expression Editor

Example 1
trim ( TRAILING 'A' , 'ABCDEFA' )

Result: 'ABCDEF'

Example 2
trim ( BOTH ' ABCDEF ' )

Result: 'ABCDEF'

tuple
Identifies a cell location (intersection) based on the specified members, each of which must be from a different dimension. Implicitly includes the current member from all dimensions not otherwise specified in the arguments. The current member of any dimension not specified in the evaluating context is assumed to be the default member of that dimension. The value of this cell can be obtained with the "value" function.

Syntax
tuple ( member { , member } )

union
This function returns the union of 2 sets "set_exp1" and "set_exp2". The result retains duplicates only when the optional keyword ALL is supplied as the third argument.

Syntax
union ( set_exp1 , set_exp2 [ , ALL ] )

upper
Returns string_exp with all lowercase characters shifted to uppercase.

Syntax
upper ( string_exp )

Example
upper ( 'abcdef' )

Result: 'ABCDEF'

value
Returns the value of the cell identified by a tuple. Note that the default member of the Measures dimension is the Default Measure

Syntax
value ( tuple )

DB2
ascii
Returns the ASCII code value of the leftmost character of the argument as an integer.

Syntax
ascii ( string_exp )

ceiling
Returns the smallest integer greater than or equal to numeric_exp.

User Guide 295

Appendix B: Using the Expression Editor

Syntax
ceiling ( numeric_exp )

char
Returns a string representation of a date/time value or a decimal number.

Syntax
char ( exp )

chr
Returns the character that has the ASCII code value specified by integer_exp. integer_exp should be between 0 and 255.

Syntax
chr ( integer_exp )

concat
Returns a string that is the result of concatenating string_exp1 with string_exp2.

Syntax
concat ( string_exp1, string_exp2 )

date
Returns a date from a single input value. exp can be a string or integer representation of a date.

Syntax
date ( exp )

day
Returns the day of the month (1-31) from date_exp. date_exp can be a date value or a string representation of a date.

Syntax
day ( date_exp )

dayname
Returns a character string containing the data source_specific name of the day (for example, Sunday through Saturday or Sun. through Sat. for a data source that uses English, or Sonntag through Samstag for a data source that uses German) for the day portion of date_exp. date_exp can be a date value or a string representation of a date.

Syntax
dayname ( date_exp )

dayofweek
Returns the day of the week in date_exp as an integer in the range 1 to 7, where 1 represents Sunday. date_exp can be a date value or a string representation of a date.

Syntax
dayofweek ( date_exp )

dayofweek_iso
Returns the day of the week in date_exp as an integer in the range 1 to 7, where 1 represents Monday. date_exp can be a date value or a string representation of a date.

296

Framework Manager

Appendix B: Using the Expression Editor

Syntax
dayofweek_iso ( date_exp )

dayofyear
Returns the day of the year in date_exp as an integer in the range 1 to 366. date_exp can be a date value or a string representation of a date.

Syntax
dayofyear ( date_exp )

days
Returns an integer representation of a date. exp can be a date value or a string representation of a date.

Syntax
days ( exp )

decimal
Returns decimal representation of string_exp1 with precision numeric_exp1, scale numeric_exp2 and decimal character string_exp2. String_exp1 must be formatted as a SQL Integer or Decimal constant.

Syntax
decimal ( string_exp1 [ , numeric_exp1 [ , numeric_exp2 [ , string_exp2 ] ] ] )

difference
Returns an integer value representing the difference between the values returned by the data source_specific soundex function for string_exp1 and string_exp2. The value returned ranges from 0 to 4, with 4 indicating the best match. Note that 4 does not mean that the strings are equal.

Syntax
difference ( string_exp1, string_exp2 )

digits
Returns the character string representation of a non-floating point number.

Syntax
digits ( numeric_exp )

double
Returns the floating-point representation of an expression. 'exp' can be either a numeric or string expression.

Syntax
double ( exp )

event_mon_state
Returns the operational state of a particular state monitor.

Syntax
event_mon_state ( string_exp )

float
Returns the floating-point representation of a number.

User Guide 297

Appendix B: Using the Expression Editor

Syntax
float ( numeric_exp )

hex
Returns the hexadecimal representation of a value.

Syntax
hex ( exp )

hour
Returns the hour (an integer from 0, which is midnight, to 23, which is 11:00 pm) from time_exp. time_exp can be a time value or a string representation of a time.

Syntax
hour ( time_exp )

insert
Returns a string where length (integer_exp2) characters have been deleted from string_exp1 beginning at start (integer_exp1) and where string_exp2 has been inserted into string_exp1 at start. The first character in a string is at position 1.

Syntax
insert ( string_exp1, integer_exp1, integer_exp2, string_exp2 )

integer
Returns the integer representation of an expression. exp can be a numeric value or a string representation of a number.

Syntax
integer ( exp )

julian_day
Returns an integer value representing the number of days from January 1, 4712 BC (the start of the Julian date calendar) to the date value specified in exp. exp can be a date value or a string representation of a date.

Syntax
julian_day ( exp )

lcase
Returns string_exp with all uppercase characters shifted to lowercase.

Syntax
lcase ( string_exp )

left
Returns the leftmost integer_exp characters of string_exp.

Syntax
left ( string_exp, integer_exp )

length
Returns the length of the operand in bytes (except for double byte string types which return the length in characters).

298

Framework Manager

Appendix B: Using the Expression Editor

Syntax
length ( exp )

locate
Returns the starting position of the first occurrence of string_exp1 within string_exp2. The search starts at position start (integer_exp) of string_exp2. The first character in a string is at position 1. If string_exp1 is not found then zero is returned.

Syntax
locate ( string_exp1, string_exp2 [ , integer_exp ] )

long_varchar
Returns a long string.

Syntax
long_varchar ( string_exp )

ltrim
Returns string_exp with leading spaces removed.

Syntax
ltrim ( string_exp )

microsecond
Returns the microsecond (time-unit) part of a value. exp can be a timestamp or a string representation of a timestamp.

Syntax
microsecond ( exp )

midnight_seconds
Returns an integer value in the range 0 to 86400 representing the number of seconds between midnight and time value specified in the argument. exp can be a time value, a timestamp or a string representation of a time.

Syntax
midnight_seconds ( exp )

minute
Returns the minute (an integer from 0-59) from time_exp. time_exp can be a time value, a timestamp or a string representation of a time.

Syntax
minute ( time_exp )

month
Returns the month (an integer from 1-12) from date_exp.

Syntax
month ( date_exp )

monthname
Returns a character string containing the data source_specific name of the month (for example, January through December or Jan. through Dec. for a data source that uses English, or Januar through Dezember for a data source that uses German) for the month portion of date_exp.

User Guide 299

Appendix B: Using the Expression Editor

Syntax
monthname ( date_exp )

quarter
Returns the quarter in date_exp as a number in the range 1 to 4, where 1 represents January 1 through March 31.

Syntax
quarter ( date_exp )

radians
Returns the number of radians converted from numeric_exp degrees.

Syntax
radians ( numeric_exp )

repeat
Returns a string consisting of string_exp repeated integer_exp times.

Syntax
repeat ( string_exp, integer_exp )

replace
Replaces all occurrences of string_exp2 in string_exp1 with string_exp3.

Syntax
replace ( string_exp1, string_exp2, string_exp3 )

right
Returns the rightmost integer_exp characters of string_exp.

Syntax
right ( string_exp, integer_exp )

round
Returns numeric_exp rounded to the nearest value integer_exp places right of the decimal point. If integer_exp is negative, numeric_exp is rounded to the nearest value absolute (integer_exp) places to the left of the decimal point, e.g., round-near (125, -1) rounds to 130.

Syntax
round ( numeric_exp, integer_exp )

rtrim
Returns string_exp with trailing spaces removed.

Syntax
rtrim ( string_exp )

second
Returns the second (an integer from 0-59) from time_exp.

Syntax
second ( time_exp )

300

Framework Manager

Appendix B: Using the Expression Editor

sign
Returns an indicator of the sign of numeric_exp: +1 if numeric_exp is positive, 0 if zero or -1 if negative.

Syntax
sign ( numeric_exp )

smallint
Returns the small integer representation of a number.

Syntax
smallint ( exp )

soundex
Returns a 4 character string code obtained by systematically abbreviating words and names in string_exp according to phonetics. Can be used to determine if two strings sound the same, e.g., does sound-of ('SMITH') = sound-of ('SMYTH').

Syntax
soundex ( string_exp )

space
Returns a string consisting of integer_exp spaces.

Syntax
space ( integer_exp )

substring
Returns the substring of string_exp that starts at position integer_exp1 for integer_exp2 characters. The first character in string_exp is at position 1.

Syntax
substring ( string_exp, integer_exp1 [ , integer_exp2 ] )

table_name
Returns an unqualified name of a table or view based on the object name in string_exp1 and the schema name given in string_exp2. It is used to resolve aliases.

Syntax
table_name ( string_exp1 [ , string_exp2 ] )

table_schema
Returns the schema name portion of the two part table or view name based on the object name in string_exp1 and the schema name in string_exp2. It is used to resolve aliases.

Syntax
table_schema ( string_exp1 [ , string_exp2 ] )

time
Returns a time from a value.

Syntax
time ( exp )

User Guide 301

Appendix B: Using the Expression Editor

timestamp
Returns a timestamp from a value or a pair of values. exp1 must represent a date value, and exp2 must represent a time value.

Syntax
timestamp ( exp1 [ , exp2 ] )

timestamp_iso
Returns a datetime in the ISO format (yyyy-mm-dd hh:mm:ss.nnnnnn) converted from the IBM format (yyyy-mm-dd-hh.mm.ss.nnnnnn). If the exp is a time, it inserts the value of the CURRENT DATE for the date elements and zero for the fractional time element.

Syntax
timestamp_iso ( exp )

timestampdiff
Returns an estimated number of intervals of type exp1 based on the difference between two timestamps. Exp2 is the result of subtracting two timestamp types and converting the result to CHAR. Valid values of exp1 are: 1 Fractions of a second; 2 Seconds; 4 Minutes; 8 Hours; 16 Days; 32 Weeks; 64 Months; 128 Quarters; 256 Years

Syntax
timestampdiff ( exp1, exp2 )

translate
Returns string_exp1 in which characters from string_exp3 are translated to the equivalent characters in string_exp2. string_exp4 is a single character that is used to pad string_exp2 if it is shorter than string_exp3. If only string_exp1 is present, then this function translates it to uppercase characters.

Syntax
translate ( string_exp1 [ , string_exp2, string_exp3 [ , string_exp4 ] ] )

truncate
Returns numeric_exp1 truncated to numeric_exp2 places RIGHT of the decimal point. If numeric_exp2 is negative, numeric_exp1 is truncated to the absolute value of numeric_exp2 places to the LEFT of the decimal point.

Syntax
truncate ( numeric_exp1, numeric_exp2 )

ucase
Returns string_exp with all lowercase characters shifted to uppercase.

Syntax
ucase ( string_exp )

value
Returns the first non-null argument (or null if all arguments are null). The Value function takes two or more arguments.

Syntax
value ( exp_list )

302

Framework Manager

Appendix B: Using the Expression Editor

varchar
Returns a VARCHAR representation of exp, with length numeric_exp.

Syntax
varchar ( exp [ , numeric_exp ] )

week
Returns the week of the year in date_exp as an integer value in the range 1 to 53.

Syntax
week ( date_exp )

year
Returns the year from date_exp.

Syntax
year ( date_exp )

DB2 Cast
cast_char
Returns the first numeric_exp characters of the value of exp cast as a string. The whole string is returned when the second argument is not specified.

Syntax
cast_char ( exp [ , numeric_exp ] )

cast_date
Returns the value of the expression cast as a date.

Syntax
cast_date ( exp )

cast_decimal
Returns the value of exp cast as a decimal with the precision of numeric_exp1 and scale of numeric_exp2.

Syntax
cast_decimal ( exp [ , numeric_exp1, numeric_exp2 ] )

cast_double
Returns the value of the expression cast as a double.

Syntax
cast_double ( exp )

cast_double_precision
Returns the value of the expression cast as a double.

Syntax
cast_double_precision ( exp )

cast_float
Returns the value of the expression cast as a float. User Guide 303

Appendix B: Using the Expression Editor

Syntax
cast_float ( exp )

cast_integer
Returns the value of the expression cast as a integer.

Syntax
cast_integer ( exp )

cast_longvarchar
Returns the value of the expression cast as a longvarchar.

Syntax
cast_longvarchar ( string_exp )

cast_smallint
Returns the value of the expression cast as a smallint.

Syntax
cast_smallint ( exp )

cast_time
Returns the value of the expression cast as a time value.

Syntax
cast_time ( string_exp )

cast_timestamp
Returns the value of the expression cast as a datetime.

Syntax
cast_timestamp ( exp )

cast_varchar
Returns the value of the expression cast as a varchar with length.

Syntax
cast_varchar ( exp, integer_exp )

DB2 Math
log
Returns the natural logarithm of numeric_exp.

Syntax
log ( numeric_exp )

log10
Returns the base ten logarithm of numeric_exp.

Syntax
log10 ( numeric_exp )

304

Framework Manager

Appendix B: Using the Expression Editor

rand
Generates a random number using integer_exp as a seed value.

Syntax
rand ( integer_exp )

DB2 Trigonometry
acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

Syntax
acos ( numeric_exp )

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
asin ( numeric_exp )

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
atan ( numeric_exp )

atan2
Returns the arctangent of the x and y coordinates specified by numeric_exp1 and numeric_exp2, respectively, in radians. The arctangent is the angle whose tangent is numeric_exp2 / numeric_exp1.

Syntax
atan2 ( numeric_exp1, numeric_exp2 )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

cot
Returns the cotangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cot ( numeric_exp )

degrees
Returns numeric_exp radians converted to degrees.

Syntax
degrees ( numeric_exp )

User Guide 305

Appendix B: Using the Expression Editor

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

Informix
cardinality
Returns the number of elements in a collection column (SET, MULTISET, LIST).

Syntax
cardinality ( string_exp )

char_length
Returns the number of logical characters (which can be distinct from the number of bytes in some East Asian locales) in string_exp.

Syntax
char_length ( string_exp )

date
Returns the date value of either string_exp or date_exp or int_exp

Syntax
date ( string_exp | date_exp | int_exp )

day
Returns an integer that represents the day of the month.

Syntax
day ( date_exp )

extend
The extend function adjusts the precision of a DATETIME or DATE expression. The expression cannot be a quoted string representation of a DATE value. If you do not specify first and last qualifiers, the default qualifiers are YEAR TO FRACTION(3). If the expression contains fields that are not specified by the qualifiers, the unwanted fields are discarded. If the first qualifier specifies a larger (that is, more significant) field than what exists in the expression, the new fields are filled in with values returned by the CURRENT function. If the last qualifier specifies a smaller field (that is, less significant) than what exists in the expression, the new fields are filled in with constant values. A missing MONTH or DAY field is filled in with 1, and the missing HOUR to FRACTION fields are filled in with 0.

Syntax
extend ( date_exp , ' { ' YEAR TO SECOND ' } ' )

306

Framework Manager

Appendix B: Using the Expression Editor

Example
EXTEND (some_date_column , {YEAR TO SECOND} )

hex
Returns the hexadecimal encoding of an integer integer_exp.

Syntax
hex ( integer_exp )

initcap
Returns string_exp, with the first letter of each word in uppercase, all other letters in lowercase. With this function, a word begins after any character other than a letter. Thus, in addition to a blank space, symbols such as commas, periods, colons, and so on, introduce a new word..

Syntax
initcap ( string_exp )

length
Returns the number of bytes in string_exp, which is not including any trailing blank spaces. For BYTE or TEXT string_exp, LENGTH returns the full number of bytes, including any trailing blank spaces.

Syntax
length ( string_exp )

lpad
Returns a copy of string_exp1 that is left-padded (string_exp2) to the total number of characters specified by integer_exp. The sequence of string_exp2 occurs as many times as necessary to make the return string the length specified by integer_exp.

Syntax
lpad ( string_exp1, integer_exp, string_exp2 )

mdy
Returns a type DATE value with three expressions that evaluate to integers that represent the month(integer_exp1), day(integer_exp2), and year(integer_exp3).

Syntax
mdy ( integer_exp1, integer_exp2, integer_exp3 )

month
Returns an integer corresponding to the month portion of date_exp.

Syntax
month ( date_exp )

octet_length
Returns the number of bytes in string_exp, including any trailing spaces.

Syntax
octet_length ( string_exp )

User Guide 307

Appendix B: Using the Expression Editor

replace
Returns a copy of string_exp1 in which every occurrence of string_exp2 is replaced by string_exp3. If you omit the string_exp3 option, every occurrence of string_exp2 is omitted from the return string.

Syntax
replace ( string_exp1, string_exp2 [ , string_exp3 ] )

round
Returns the rounded value of an numeric_exp. If you omit the integer_exp, the value is rounded to zero digits or to the units place. The digit range of 32 (+ and -) refers to the entire decimal value.

Syntax
round ( numeric_exp [ , integer_exp ] )

rpad
Returns a copy of string_exp1 that is right-padded (string_exp2) to the total number of characters specified by integer_exp. The sequence of string_exp2 occurs as many times as necessary to make the return string the length specified by integer_exp.

Syntax
rpad ( string_exp1, integer_exp, string_exp2 )

substr
Returns the substring of string_exp that starts at position integer_exp1. The first character in string_exp is at position 1. integer_exp2 can be used to select fewer characters, by default it selects character to the end of the string.

Syntax
substr ( string_exp, integer_exp1 [ , integer_exp2 ] )

to_char
Returns the character string of date_exp with the specified string_exp formatting. You can use this function only with built-in data types.

Syntax
to_char ( date_exp, string_exp )

to_date
Returns the string_exp1 as a date according to the date format you specify in the string_exp2 parameter. If string_exp1 is NULL, then a NULL value is returned.

Syntax
to_date ( string_exp1, string_exp2 )

trunc
Returns the truncated value of a numeric_exp. If you omit integer_exp, the value is truncated to zero digits or to the units place. The digit limitation of 32 (+ and -) refers to the entire decimal value.

Syntax
trunc ( numeric_exp [ , integer_exp ] )

308

Framework Manager

Appendix B: Using the Expression Editor

weekday
Returns an integer that represents the day of the week; zero (0) represents Sunday, one (1) represents Monday, and so on.

Syntax
weekday ( date_exp )

year
Returns a four-digit integer that represents the year.

Syntax
year ( date_exp )

Informix Math
log10
Returns the log of a numeric_exp to base 10.

Syntax
log10 ( numeric_exp )

logn
Returns the natural logarithm of a numeric_exp.

Syntax
logn ( numeric_exp )

root
Returns the root value of a numeric_exp. Requires at least one numeric argument (the radians argument). If only the numeric_exp1 is supplied, the value 2 is used as a default value for numeric_exp2; 0 cannot be used as the value of numeric_exp2.

Syntax
root ( numeric_exp1[ , numeric_exp2 ] )

Informix Trigonometry
acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

Syntax
acos ( numeric_exp )

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
asin ( numeric_exp )

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

User Guide 309

Appendix B: Using the Expression Editor

Syntax
atan ( numeric_exp )

atan2
Returns the arctangent of the x and y coordinates specified by numeric_exp1 and numeric_exp2, respectively, in radians. The arctangent is the angle whose tangent is numeric_exp1.

Syntax
atan2 ( numeric_exp1, numeric_exp2 )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

MS Access
ascii
Returns a number representing the ascii code value of the leftmost character of string_exp.

Syntax
ascii(string_exp)

ceiling
Returns the smallest integer greater than or equal to numeric_exp.

Syntax
ceiling(numeric_exp)

chr
Returns the character that has the ASCII code value specified by integer_exp. integer_exp should be between 0 and 255.

Syntax
chr(integer_exp)

concat
Returns a string that is the result of concatenating string_exp1 to string_exp2.

310

Framework Manager

Appendix B: Using the Expression Editor

Syntax
concat(string_exp1, string_exp2)

curdate
Returns a date value representing the current date of the computer that the database software runs on.

Syntax
curdate()

curtime
Returns a time value representing the current time of the computer that the database software runs on.

Syntax
curtime()

dayname
Returns a character string containing the data source_specific name of the day (for example, Sunday through Saturday or Sun. through Sat. for a data source that uses English, or Sonntag through Samstag for a data source that uses German) for the day portion of date_exp.

Syntax
dayname(date_exp)

dayofmonth
Returns the day of the month (1-31) from date_exp. Returns the days field (a signed integer) from interval_exp.

Syntax
dayofmonth(date_exp|interval_exp)

dayofweek
Returns the day of the week in date_exp as an integer in the range 1 to 7, where 1 represents Monday.

Syntax
dayofweek(date_exp)

dayofyear
Returns the day of the year in date_exp as an integer in the range 1 to 366.

Syntax
dayofyear(date_exp)

downshift
Returns string_exp with all uppercase characters shifted to lowercase.

Syntax
downshift(string_exp)

hour
Returns the hour (an integer from 0, which is midnight, to 23, which is 11:00 pm) from time_exp.

User Guide 311

Appendix B: Using the Expression Editor

Syntax
hour(time_exp)

lcase
Returns string_exp with all uppercase characters shifted to lowercase.

Syntax
lcase(string_exp)

left
Returns the leftmost integer_exp characters of string_exp.

Syntax
left(string_exp, integer_exp)

length
Returns the number of characters in string_exp, excluding trailing blanks and the string termination character.

Syntax
length(string_exp)

locate
Returns the starting position of the first occurrence of string_exp1 within string_exp2. The search starts at position start (integer_exp) of string_exp2. The first character in a string is at position 1. If string_exp1 is not found then zero is returned.

Syntax
locate(string_exp1, string_exp2 [ , integer_exp ] )

ltrim
Returns string_exp with leading spaces removed.

Syntax
ltrim(string_exp)

minute
Returns the minute (an integer from 0-59) from time_exp.

Syntax
minute(time_exp)

month
Returns the month (an integer from 1-12) from date_exp.

Syntax
month(date_exp)

monthname
Returns a character string containing the data source_specific name of the month (for example, January through December or Jan. through Dec. for a data source that uses English, or Januar through Dezember for a data source that uses German) for the month portion of date_exp.

Syntax
monthname(date_exp)

312

Framework Manager

Appendix B: Using the Expression Editor

now
Returns a datetime value representing the current date and time of the computer that the database software runs on.

Syntax
now()

position
Returns the starting position of string_exp1 in string_exp2. The first character in a string is at position 1.

Syntax
position(string_exp1, string_exp2)

quarter
Returns the quarter in date_exp as a number in the range 1 to 4, where 1 represents January 1 through March 31.

Syntax
quarter(date_exp)

right
Returns the rightmost integer_exp characters of string_exp.

Syntax
right(string_exp, integer_exp)

round
Returns numeric_exp rounded to the nearest value integer_exp places right of the decimal point. If integer_exp is negative, numeric_exp is rounded to the nearest value absolute (integer_exp) places to the left of the decimal point.

Syntax
round(numeric_exp, integer_exp)

rtrim
Returns string_exp with trailing spaces removed.

Syntax
rtrim(string_exp)

sign
Returns an indicator of the sign of numeric_exp: +1 if numeric_exp is positive, 0 if zero or -1 if negative.

Syntax
sign(numeric_exp)

space
Returns a string consisting of integer_exp spaces.

Syntax
space(integer_exp)

User Guide 313

Appendix B: Using the Expression Editor

substr
Returns the substring of string_exp that starts at position integer_exp1 for integer_exp2 characters. The first character in string_exp is at position 1.

Syntax
substr(string_exp, integer_exp1, integer_exp2)

substring
Returns the substring of string_exp that starts at position integer_exp1 for integer_exp2 characters. The first character in string_exp is at position 1.

Syntax
substring(string_exp, integer_exp1, integer_exp2)

truncate
Returns string_exp with trailing spaces removed.

Syntax
truncate(string_exp)

ucase
Returns string_exp with all lowercase characters shifted to uppercase.

Syntax
ucase(string_exp)

upshift
Returns string_exp with all lowercase characters shifted to uppercase.

Syntax
upshift(string_exp)

week
Returns the week of the year in date_exp as an integer value in the range 1 to 53.

Syntax
week(date_exp)

year
Returns the year from date_exp.

Syntax
year(date_exp)

MS Access Cast
cast_decimal
Returns the value of the expression cast as a decimal.

Syntax
cast_decimal(exp)

cast_float
Returns the value of the expression cast as a float. 314 Framework Manager

Appendix B: Using the Expression Editor

Syntax
cast_float(exp)

cast_integer
Returns the value of the expression cast as a integer.

Syntax
cast_integer(exp)

cast_numeric
Returns the value of string_exp cast as a numeric value.

Syntax
cast_numeric(string_exp)

cast_real
Returns the value of the expression cast as a real.

Syntax
cast_real(exp)

cast_smallint
Returns the value of the expression cast as a smallint.

Syntax
cast_smallint(exp)

cast_varchar
Returns the value of the expression cast as a varchar.

Syntax
cast_varchar(exp)

MS Access Math
log
Returns the natural logarithm of numeric_exp.

Syntax
log(numeric_exp)

rand
Generates a random number using integer_exp as a seed value.

Syntax
rand(integer_exp)

MS Access Trigonometry
atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

User Guide 315

Appendix B: Using the Expression Editor

Syntax
atan(numeric_exp)

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos(numeric_exp)

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin(numeric_exp)

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan(numeric_exp)

Oracle
add_months
Returns the datetime resulting from adding integer_exp months to date_exp.

Syntax
add_months ( date_exp, integer_exp )

ascii
Returns a number representing the ascii code value of the leftmost character of string_exp, e.g. ascii('A') is 65.

Syntax
ascii ( string_exp )

chr
Returns the character that has the ASCII code value specified by integer_exp. integer_exp should be between 0 and 255.

Syntax
chr ( integer_exp )

concat
Returns a string that is the result of concatenating string_exp1 to string_exp2.

Syntax
concat ( string_exp1, string_exp2 )

decode
DECODE compares expr to each search value one by one. If expr is equal to a search, then returns the corresponding result. If no match is found, then returns default. If default is omitted, then returns null.

316

Framework Manager

Appendix B: Using the Expression Editor

Syntax
decode ( expr , search , result [, search , result]... [, default] )

dump
Returns internal representation of 'expr' with the format of numeric_exp1 starting from position numeric_exp2 for numeric_exp3.

Syntax
dump ( expr [ , numeric_exp1 [ , numeric_exp2 [ , numeric_exp3 ] ] ] )

greatest
Returns the greatest value in a list of expressions.

Syntax
greatest ( exp_list )

initcap
Returns string_exp, with the first letter of each word in uppercase, all other letters in lowercase. Words are delimited by white space or characters that are not alphanumeric.

Syntax
initcap ( string_exp )

instr
Searches string_exp1 from the integer_exp1 position for the (integer_exp2)th occurance of string_exp2. If integer_exp1 is negative then the search is backwards from the end of string_exp1. Returns an integer indicating the position of string_exp2.

Syntax
instr ( string_exp1, string_exp2 [ , integer_exp1 [ , integer_exp2 ] ] )

instrb
Searches string_exp1 from the integer_exp1 position for the (integer_exp2)th occurance of string_exp2. If integer_exp1 is negative then the search is backwards from the end of string_exp1. The result returned indicates the position (byte number) where search was found.

Syntax
instrb ( string_exp1, string_exp2 [ , integer_exp1 [ , integer_exp2 ] ] )

least
Returns the least value in a list of expressions.

Syntax
least ( exp_list )

length
Returns the number of characters in string_exp.

Syntax
length ( string_exp )

lengthb
Returns the number of bytes in string_exp.

User Guide 317

Appendix B: Using the Expression Editor

Syntax
lengthb ( string_exp )

lpad
Returns string_exp1 padded to length integer_exp with occurrences of string_exp2. If string_exp1 is longer than integer_exp then returns the appropriate portion of string_exp1.

Syntax
lpad ( string_exp1, integer_exp [ , string_exp2 ] )

ltrim
Returns string_exp1, with leading characters removed up to the first character not in string_exp2, e.g. ltrim('xyxXxyAB', 'xy') returns 'XxyAB'.

Syntax
ltrim ( string_exp1 [ , string_exp2 ] )

months_between
Returns the number of months from date_exp1 to date_exp2. If date_exp1 is later than date_exp2 then the result will be a positive number. The days and time portion of the difference are ignored, i.e. the months are not rounded, except if date_exp1 and date_exp2 are the last days of a month.

Syntax
months_between ( date_exp1, date_exp2 )

new_time
Returns the Datetime in timezone 'new_tz' for 'datetime' in 'old_tz' timezone. 'Old_tz' and 'new_tz' can be one of 'AST', 'ADT', 'BST', 'BDT', 'CST', 'CDT', 'EST', 'EDT', 'HST', 'HDT', 'MST', 'MDT', 'NST', 'PST', 'PDT', 'YST' or 'YDT'.

Syntax
new_time ( datetime_exp, old_tz, new_tz )

next_day
Returns the datetime of the first weekday named by string_exp that is later than datetime_exp. The return value has the same hours, minutes, and seconds as datetime_exp.

Syntax
next_day ( datetime_exp, string_exp )

nls_initcap
Returns string_exp1 with the first letter of each word in uppercase, all other letters in lowercase. Words are delimited by white space or characters that are not alphanumeric. string_exp2 specifies the sorting sequence.

Syntax
nls_initcap ( string_exp1 [ , string_exp2 ] )

nls_lower
Returns string_exp1 with all letters in lowercase. string_exp2 specifies the sorting sequence.

Syntax
nls_lower ( string_exp1 [ , string_exp2 ] )

318

Framework Manager

Appendix B: Using the Expression Editor

nls_upper
Returns string_exp1 with all letters in uppercase. string_exp2 specifies the sorting sequence.

Syntax
nls_upper ( string_exp1 [ , string_exp2 ] )

nvl
If exp is null (missing) returns constant. If exp is not null returns exp. Valid for numeric_exp, string_exp, date_exp, and time_exp.

Syntax
nvl ( exp, constant )

replace
Replaces all occurrences of string_exp2 in string_exp1 with string_exp3. If string_exp3 is not specified then it replaces all occurrences with null (ie: removes all occurances of string_exp2).

Syntax
replace ( string_exp1, string_exp2 [ , string_exp3 ] )

round
Returns numeric_exp rounded to the nearest value integer_exp places right of the decimal point. If integer_exp is negative, numeric_exp is rounded to the nearest value absolute (integer_exp) places to the left of the decimal point, e.g., round (125, -1) rounds to 130.

Syntax
round ( numeric_exp [ , integer_exp ] )

rpad
Returns string_exp1 right-padded to length integer_exp with occurrences of string_exp2. If string_exp1 is longer than integer_exp then returns the appropriate portion of string_exp1. If string_exp2 is not specified then spaces are used.

Syntax
rpad ( string_exp1, integer_exp [ , string_exp2 ] )

rtrim
Returns string_exp1, with final characters removed after the last character not in string_exp2, e.g. rtrim('ABxXxyx', 'xy') returns 'ABxX'. If string_exp2 is not specified it removes th final space characters.

Syntax
rtrim ( string_exp1 [ , string_exp2 ] )

sign
Returns an indicator of the sign of numeric_exp: +1 if numeric_exp is positive, 0 if zero or -1 if negative.

Syntax
sign ( numeric_exp )

soundex
Returns a character string containing the phonetic representation of string_exp.

User Guide 319

Appendix B: Using the Expression Editor

Syntax
soundex ( string_exp )

substr
Returns the substring of string_exp that starts at position integer_exp1. The first character in string_exp is at position 1. integer_exp2 can be used to select fewer characters, by default it selects character to the end of the string.

Syntax
substr ( string_exp, integer_exp1 [ , integer_exp2 ] )

substrb
Same as substr, except that the arguments are expressed in bytes (not characters).

Syntax
substrb ( string_exp, numeric_exp1 [ , numeric_exp2 ] )

{sysdate}
Returns a datetime value representing the current date and time of the computer that the database software runs on.

Syntax
{ sysdate }

to_char
Returns the string representation of exp with the format of string_exp. exp can either be a date value or a numeric value.

Syntax
to_char ( exp [ , string_exp ] )

to_date
Converts string_exp1 to a datetime value as specified by the format string_exp2. string_exp3 specifies format elements such as language.

Syntax
to_date ( string_exp1 [ , string_exp2 [ , string_exp3 ] ] )

to_number
Converts string_exp1 to a numeric value as specified by the format string_exp2. string_exp3 specifies format elements such as currency information.

Syntax
to_number ( string_exp1, string_exp2, string_exp3 )

translate
Returns string_exp1, with all occurrences of each character in string_exp2 replaced by its corresponding character in string_exp3.

Syntax
translate ( string_exp1, string_exp2, string_exp3 )

trunc
Truncates the date_exp using the format specified by string_exp. For example, if string_exp is 'YEAR' then date_exp is truncated to the first day of the year.

320

Framework Manager

Appendix B: Using the Expression Editor

Syntax
trunc ( date_exp, string_exp )

trunc
Truncates digits from numeric_exp1 using numeric_exp2 as the precision.

Syntax
trunc ( numeric_exp1, numeric_exp2 )

{user}
Returns the username of the current Oracle user.

Syntax
{ user }

vsize
Returns the number of bytes in the internal representation of 'exp'. 'exp' must be a string expression.

Syntax
vsize ( exp )

Oracle Cast
cast_varchar
Returns the value of the expression cast as a varchar. exp can be of type numeric, date or timestamp.

Syntax
cast_varchar ( exp )

cast_timestamp
Returns the value of the expression cast as a timestamp. exp can be of type string or date. For example, cast_timestamp( '1999-12-31 23:59:59.23' ).

Syntax
cast_timestamp ( exp )

Oracle Math
log
Returns the logarithm of numeric_exp2 to the base numeric_exp1.

Syntax
log ( numeric_exp1, numeric_exp2 )

Oracle Trigonometry
acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

User Guide 321

Appendix B: Using the Expression Editor

Syntax
acos ( numeric_exp )

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
asin ( numeric_exp )

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
atan ( numeric_exp )

atan2
Returns the arctangent of the x and y coordinates specified by numeric_exp1 and numeric_exp2, respectively, in radians. The arctangent is the angle whose tangent is numeric_exp2 / numeric_exp1.

Syntax
atan2 ( numeric_exp1 ,numeric_exp2 )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

cosh
Returns the hyperbolic cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cosh ( numeric_exp )

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

sinh
Returns the hyperbolic sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sinh ( numeric_exp )

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

322

Framework Manager

Appendix B: Using the Expression Editor

tanh
Returns the hyperbolic tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tanh ( numeric_exp )

Red Brick
concat
This function concatenates character strings and returns the concatenated string of characters.

Syntax
concat ( string_exp1 , string_exp2 )

current_user
Returns the database username (authorization ID) of the current user.

Syntax
current_user

date
This function creates a date value from a character string or a timestamp expression and returns a date data type. The expression can be either characters or timestamp.

Syntax
date ( expression )

dateadd
This function adds an interval to a datetime value and returns a result that is the same datetime data type as that of datetime_expression. The datepart refers to year, month, day, hour, minute, second. The interval must be an integer and datetime_exp can be date, time or timestamp.

Syntax
dateadd ( { datepart }, interval, datetime_exp )

datediff
This function finds the difference between two datetime expressions and returns an integer result in datepart units. The datepart refers to year, month, day, hour, minute, second. The datetime_exp can be date, time or timestamp.

Syntax
datediff ( { datepart }, datetime_exp, datetime_exp )

datename
This function extracts the specified datepart component and returns its value as a character string. The datepart refers to year, month, day, hour, minute, second. The datetime_exp can be date, time or timestamp.

Syntax
datename ( { datepart }, datetime_exp )

User Guide 323

Appendix B: Using the Expression Editor

dec
This function converts a specified value to a decimal value and returns a value with the data type decimal (precision, scale). The default value of precision is 9. The default value of scale is 0.

Syntax
dec ( expression, [precision, scale] )

decode
This function compares and converts an expression to another value. If the expression matches target, it is replaced by the corresponding replacement; otherwise the expression is replaced by default or by NULL if no default is specified. The expressions can be any data type and all expressions must be the same data type.

Syntax
decode ( expression, target, replacement [,default] )

float
This function converts a specified value into a double-precision floating-point value.

Syntax
float ( numeric_exp )

ifnull
This function tests an expression for missing values and replaces each one with a specified value. If expression is NULL, this function returns substitute; otherwise it returns the value of the expression. The expressions can be any data type and all expressions must be the same data type.

Syntax
ifnull ( expression , substitute )

int
This function converts a specified numeric string into an integer valueand returns an integer value. If the argument is null, this function returns NULL.

Syntax
int ( numeric_exp )

length
If the argument is not null, this function returns an integer result specifying the number of characters in the string; otherwise the result is NULL.

Syntax
length ( string_exp )

lengthb
If the argument is not null, this function returns an integer result specifying the number of bytes in the string. If the argument is null, the result is NULL.

Syntax
lengthb ( string_exp )

ltrim
If the argument is not null, this function removes leading blanks from the character string; otherwise the result is NULL.

324

Framework Manager

Appendix B: Using the Expression Editor

Syntax
ltrim ( string_exp )

nullif
This function returns NULL if both expressions have the same value. If the expressions have different values, the value of the first expression is returned. The exp1 and exp2 can be any data type and must be the same data type.

Syntax
nullif ( exp1, exp2 )

positionb
If the first string_exp is located, this function returns an integer that is relative to the beginning byte position of the first string_exp in the second string_exp. If the first string_exp is not located, the result is 0. If the first string_exp is of zero length, the result is 1. If the first string_exp is null, an error message is returned. If the second string_exp is null, the result is 0.

Syntax
positionb ( string-exp, string_exp )

real
This function returns a real value. If the argument is null, this function returns NULL.

Syntax
real ( numeric_exp )

rtrim
If the argument is not null, this function removes trailing blanks from the character string; otherwise the result is NULL.

Syntax
rtrim ( string_exp )

sign
This function calculates the sign of the expression, and returns 1 for a positive value, 1 for a negative value, and 0 for zero.

Syntax
sign ( numeric_exp )

string
This function converts numeric or datetime values to character strings. The expression can be numeric or datetime.

Syntax
string ( expression [, length [, scale]] )

substr
If the first argument is not null, this function returns the substring that begins at position start and continues for length characters. If length is not specified, this function returns a substring from start to the end of string_exp.

Syntax
substr ( string_exp, start_integer, length_integer )

User Guide 325

Appendix B: Using the Expression Editor

substrb
If the first argument is not null, this function returns the substring that begins at position start and continues for length bytes. If length is not specified, this function returns a substring from start to the end of string_exp.

Syntax
substrb ( string_exp, start_integer, length_integer )

time
This function creates a time value from a character string or a time-stamp data type expression.

Syntax
time ( expression )

timestamp
This function creates a time-stamp value from a character string.

Syntax
timestamp ( timestamp_exp )

timestamp
This function creates a time-stamp value from time and date values. If there are two arguments, the first must be a date expression and the second must be a time expression, separated by a comma (,). If either the date expression or the time expression is null, the resulting time-stamp expression is also null.

Syntax
timestamp ( date_exp, time_exp )

to_char
This function is a datetime scalar function that operates on a date, time, or timestamp data type and returns the character string specified by a given format.

Syntax
to_char ( source_date, format_str )

SQL Server
ascii
Returns a number representing the ascii code value of the leftmost character of string_exp, e.g. ascii('A') is 65.

Syntax
ascii(string_exp)

char
Returns the character that has the ASCII code value specified by integer_exp. integer_exp should be between 0 and 255. For example, char(65) has the value 'A'.

Syntax
char(integer_exp)

datalength
Returns the length of the string. 326 Framework Manager

Appendix B: Using the Expression Editor

Syntax
datalength(string_exp)

dateadd
Returns the date resulting from adding integer_exp units indicated by datepart(e.g. day, month, year) to date_exp.

Syntax
dateadd({datepart}, integer_exp, date_exp)

datediff
Returns the number of units indicated by datepart(e.g. day, month, year) between date_exp1 and date_exp2.

Syntax
datediff({datepart}, date_exp1, date_exp2)

day
Returns the day portion of date_exp. Same as extract(day from date_exp).

Syntax
day(date_exp)

difference
Returns an integer value representing the difference between the values returned by the data source_specific soundex function for string_exp1 and string_exp2. The value returned ranges from 0 to 4, with 4 indicating the best match. Note that 4 does not mean that the strings are equal.

Syntax
difference(string_exp1, string_exp2)

getdate
Returns a datetime value representing the current date and time of the computer that the database software runs on.

Syntax
getdate()

ltrim
Returns string_exp with leading spaces removed.

Syntax
ltrim(string_exp)

month
Returns the month portion of date_exp. Same as extract(month from date_exp).

Syntax
month(date_exp)

replicate
Returns a string consisting of string_exp repeated integer_exp times.

User Guide 327

Appendix B: Using the Expression Editor

Syntax
replicate(string_exp, integer_exp)

right
Returns the rightmost integer_exp characters of string_exp.

Syntax
right(string_exp, integer_exp)

round
Returns numeric_exp rounded to the nearest value integer_exp places right of the decimal point.

Syntax
round(numeric_exp,integer_exp)

sign
Returns an indicator of the sign of numeric_exp: +1 if numeric_exp is positive, 0 if zero or -1 if negative.

Syntax
sign(numeric_exp)

soundex
Returns a four character string representing the sound of the words in string_exp.

Syntax
soundex(string_exp)

space
Returns a string consisting of integer_exp spaces.

Syntax
space(integer_exp)

str
Returns a string representation of numeric_exp. integer_exp1 is the length of the string returned. integer_exp2 is the number of decimal digits.

Syntax
str(numeric_exp [ , integer_exp1 [ , integer_exp2 ] ] )

stuff
Returns a string where length (integer_exp2) characters have been deleted from string_exp1 beginning at start (integer_exp1) and where string_exp2 has been inserted into string_exp1 at start. The first character in a string is at position 1.

Syntax
stuff(string_exp1, integer_exp1, integer_exp2, string_exp2)

year
Returns the year portion of date_exp. Same as extract(year from date_exp).

Syntax
year(date_exp)

328

Framework Manager

Appendix B: Using the Expression Editor

SQL Server Cast

cast_char
Returns the value of the expression cast as a char.

Syntax
cast_char(exp)

cast_float
Returns the value of the expression cast as a float.

Syntax
cast_float(exp)

cast_integer
Returns the value of the expression cast as an integer.

Syntax
cast_integer(exp)

cast_real
Returns the value of the expression cast as a real.

Syntax
cast_real(exp)

cast_smallint
Returns the value of the expression cast as a small integer.

Syntax
cast_smallint(exp)

cast_timestamp
Returns the value of the expression cast as a datetime.

Syntax
cast_timestamp(exp)

cast_varchar
Returns the value of the expression cast as a varchar.

Syntax
cast_varchar(exp)

SQL Server Math

log
Returns the natural logarithm of numeric_exp.

Syntax
log(numeric_exp)

User Guide 329

Appendix B: Using the Expression Editor

log10
Returns the base ten logarithm of numeric_exp.

Syntax
log10(numeric_exp)

pi
Returns the constant value of pi as a floating point value.

Syntax
pi()

rand
Generates a random number using integer_exp as a seed value.

Syntax
rand(integer_exp)

SQL Server Trigonometry

acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

Syntax
acos(numeric_exp)

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
asin(numeric_exp)

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
atan(numeric_exp)

atn2
Returns the arctangent of the x and y coordinates specified by numeric_exp1 and numeric_exp2, respectively, in radians. The arctangent is the angle whose tangent is numeric_exp1.

Syntax
atn2(numeric_exp1, numeric_exp2)

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos(numeric_exp)

330

Framework Manager

Appendix B: Using the Expression Editor

cot
Returns the cotangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cot(numeric_exp)

degrees
Returns numeric_exp radians converted to degrees.

Syntax
degrees(numeric_exp)

radians
Returns the number of radians converted from numeric_exp degrees.

Syntax
radians(numeric_exp)

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin(numeric_exp)

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan(numeric_exp)

Teradata
account
This function returns the account string for the current user.

Syntax
{account}

bytes
This function returns the number of bytes contained in the specified byte string.The byte_exp are restricted to BYTE or VARBYTE.

Syntax
bytes ( byte_exp )

case_n
This function evaluates a list of conditions and returns the position of the first condition that evaluates to TRUE, provided that no prior condition in the list evaluates to UNKNOWN. The NO CASE is an optional condition that evaluates to TRUE if every conditional_expression in the list evaluates to FALSE. The NO CASE OR UNKNOWN condition evaluates to TRUE if every conditional_expression in the list evaluates to FALSE, or if a conditional_expression evaluates to UNKNOWN and all prior conditions in the list evaluate to FALSE. The UNKNOWN is an optional condition that evaluates to TRUE if a conditional_expression evaluates to UNKNOWN and all prior conditions in the list evaluate to FALSE. User Guide 331

Appendix B: Using the Expression Editor

Syntax
case_n ( condition_exp_list [, NO CASE | UNKNOWN | NO CASE OR UNKNOWN [, UNKNOWN ]] )

char2hexint
This function returns the hexadecimal representation for a character string.

Syntax
char2hexint ( string_exp )

characters
This function returns an integer value representing the number of logical characters or bytes contained in the specified operand string.

Syntax
characters ( string_exp )

database
This function returns the name of the default database for the current user.

Syntax
{database}

date
This function returns the current date.

Syntax
{date}

format
This function returns the declared format for the named expression. The data type returned by a FORMAT phrase is a variable character string of up to 30 characters.

Syntax
format ( expression )

index
This function returns the position in string_exp1 where string_exp2 starts.

Syntax
index ( string_exp1, string_exp2 )

log
Computes the base 10 logarithm of an argument. The numeric_exp is a non-zero, positive numeric expression.

Syntax
log ( numeric_exp )

nullif
This function returns NULL if scalar_exp1 and scalar_exp2 are equal. Otherwise, it returns its first argument, scalar_exp1. The scalar_exp1 and scalar_exp2 can be any data type.

Syntax
nullif ( scalar_exp1, scalar_exp2 )

332

Framework Manager

Appendix B: Using the Expression Editor

nullifzero
This function converts data from zero to null to avoid problems with division by zero.

Syntax
nullifzero ( numeric_exp )

profile
This function returns the current profile for the session or NULL if none.

Syntax
{profile}

random
This function returns a random integer number for each row of the results table. The lower_bound and upper_bound are integer constants. The limits for lower_bound, upper_bound range from -2147483648 to 2147483647, inclusive. The upper_bound must be greater than or equal to lower_bound.

Syntax
random ( lower_bound, upper_bound )

range_n
This function evaluates a test_exp and maps the result into a list of specified ranges and returns the position of the range in the list. start_exp and end_exp are constants or constant expressions and must be the same data type as test_exp. Use an asterisk ( * ) for the starting boundary of the first range to indicate the lowest possible value. Use an asterisk ( * ) for the ending boundary of the last range to indicate the highest possible value. An asterisk is compatible with any data type. The range_size is a constant or constant expression. A range that specifies an EACH phrase is equivalent to a series of ranges. The value of range_size must be greater than zero. NO RANGE is an optional range to handle a test_exp that does not map into any of the specified ranges. The NO RANGE OR UNKNOWN option handles a test_exp that does not map into any of the specified ranges, or a test_exp that evaluates to NULL when RANGE_N does not specify the range BETWEEN * AND *. UNKNOWN is an option to handle a test_expression that evaluates to NULL when RANGE_N does not specify the range BETWEEN * AND *.

Syntax
range_n ( test_exp BETWEEN start_exp | start_exp_list | * AND end_exp | * [ EACH range_size [, NO RANGE [ OR UNKNOWN | , UNKNOWN ] | UNKNOWN ] ])

role
This function returns the current role for the session or NULL if none.

Syntax
{role}

session
This function returns the number of the session for the current user.

Syntax
{session}

soundex
This function returns a character string that represents the Soundex code for string_exp.

Syntax
soundex ( string_exp )

User Guide 333

Appendix B: Using the Expression Editor

time
This function returns the current time based on a 24-hour day.

Syntax
{time}

type
This function returns the data type defined for an expression.

Syntax
type ( expression )

user
This function returns the user name of the current user.

Syntax
{user}

vargraphic
This function Returns a character string that represents the vargraphic code for string_exp.

Syntax
vargraphic ( string_exp )

zeroifnull
This function converts data from null to 0 to avoid cases where a null result creates an error. If the numeric_exp is not null, it returns the value of the numeric_exp, if numeric_exp is a character string, it is converted to a numeric value of FLOAT data type. If the numeric_exp is null or zero, it returns zero.

Syntax
zeroifnull ( numeric_exp )

Teradata Trigonometry
acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp. The values of numeric_exp must be between -1 and 1, inclusive.

Syntax
acos ( numeric_exp )

acosh
Returns the inverse hyperbolic cosine of an argument. The numeric_exp can be any real number equal to or greater than 1.

Syntax
acosh ( numeric_exp )

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp. The values of numeric_exp must be between -1 and 1, inclusive.

334

Framework Manager

Appendix B: Using the Expression Editor

Syntax
asin ( numeric_exp )

asinh
Returns the inverse hyperbolic sine of an argument. The numeric_exp can be any real number.

Syntax
asinh ( numeric_exp )

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
atan ( numeric_exp )

atan2
Returns the arctangent of the x and y coordinates specified by numeric_exp1 and numeric_exp2, respectively, in radians. ATAN2(x,y) equals ATAN(y/x), except that x can be 0 in ATAN2(x,y).The returned angle is between - and radians, excluding .

Syntax
atan2 ( numeric_exp1, numeric_exp2 )

atanh
Returns the inverse hyperbolic tangent of an argument. The numeric_exp can be any real number between 1 and -1, excluding 1 and -1.

Syntax
atanh (numeric_exp )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

cosh
Returns the hyperbolic cosine of an argument. The numeric_exp can be any real number.

Syntax
cosh ( numeric_exp )

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

sinh
Returns the hyperbolic sine of an argument. The numeric_exp can be any real number.

Syntax
sinh ( numeric_exp )

User Guide 335

Appendix B: Using the Expression Editor

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

tanh
Returns the hyperbolic tangent of an argument. The numeric_exp can be any real number.

Syntax
tanh ( numeric_exp )

SAP BW
SAP BW OLAP
characteristicValue
Creates the unique SAP BW identifier for a query item value that represents an SAP BW key value. Useful for identifying leaf-level query item values in unbalanced hierarchies.

Syntax
characteristicValue ( query_subject , query_item_value )

SAP BW Trigonometry
arccos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

Syntax
arccos ( numeric_exp )

arcsin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
arcsin ( numeric_exp )

arctan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
arctan ( numeric_exp )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

336

Framework Manager

Appendix B: Using the Expression Editor

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

coshyp
Returns the hyperbolic cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
coshyp ( numeric_exp )

sinhyp
Returns the hyperbolic sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sinhyp ( numeric_exp )

tanhyp
Returns the hyperbolic tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tanhyp ( numeric_exp )

SAP BW Math
log10
Returns the base ten logarithm of numeric_exp.

Syntax
log10 ( numeric_exp )

ln
Returns the natural logarithm of the numeric_exp.

Syntax
ln ( numeric_exp )

exp
Returns e raised to the power of numeric_exp. The constant e is the base of the natural logarithm. See also log.

Syntax
exp ( numeric_exp )

User Guide 337

Appendix B: Using the Expression Editor

sqrt
Returns the square root of numeric_exp. numeric_exp must be non-negative.

Syntax
sqrt ( numeric_exp )

Sybase
ascii
Returns a number representing the ascii code value of the leftmost character of string_exp.

Syntax
ascii ( string_exp )

Example
ascii( 'A' )

Result: 65

char
Converts a single-byte integer value to a character value. char is usually used as the inverse of ascii. integer_exp must be between 0 and 255. Returns a char datatype. If the resulting value is the first byte of a multibyte character, the character may be undefined.

Syntax
char ( integer_exp )

charindex
Searches string_exp2 for the first occurrence of string_exp1and returns an integer, which represents its starting position. If string_exp1 is not found, it returns 0. If string_exp1 contains wildcard characters, charindex treats it them as literals

Syntax
charindex ( string_exp1, string_exp2 )

dateadd
Returns the date resulting from adding integer_exp units indicated by datepart(e.g. day, month, year) to date_exp.

Syntax
dateadd ( ' { ' datepart ' } ' , integer_exp, date_exp )

datediff
Returns the number of units indicated by datepart(e.g. day, month, year) between date_exp1 and date_exp2.

Syntax
datediff ( ' { ' datepart ' } ' , date_exp1, date_exp2 )

datename
Returns part of a datetime, smalldatetime, date or time value as an ASCII string

Syntax
datename ( ' { ' datepart ' } ' , date_exp )

338

Framework Manager

Appendix B: Using the Expression Editor

datepart
Returns part of a datetime, smalldatetime, date or time value (for example, the month) as an integer

Syntax
datepart ( ' { ' datepart ' } ' , date_exp )

difference
Returns an integer value representing the difference between the values returned by the data source_specific soundex function for string_exp1 and string_exp2. The value returned ranges from 0 to 4, with 4 indicating the best match. Note that 4 does not mean that the strings are equal.

Syntax
difference ( string_exp1, string_exp2 )

getdate
Returns current system date and time.

Syntax
getdate ()

ltrim
Returns string_exp with leading spaces removed.

Syntax
ltrim ( string_exp )

patindex
Returns an integer which represents the starting position if the first occurrence of string_exp1 is in the string_exp2; returns 0 if string-exp1 is not found. By default, patindex returns the offset in characters. To return offset in bytes, that is, multibyte character string, specify using bytes. The % wildcard character must precede and follow pattern in string_exp1, except when searching for first or last characters

Syntax
patindex ( string_exp1, string_exp2 [ using {bytes | chars | characters} ] )

rand
Returns a random float value between 0 and 1, using the optional integer as a seed value.

Syntax
rand ( integer_exp )

replicate
Returns a string with the same datatype as string_exp, containing the same expression repeated integer_exp times or as many times as will fit into a 225-byte space, whichever is less.

Syntax
replicate ( string_exp, integer_exp )

reverse
Returns the reverse of the character or binary expression; if string_exp is "abcd", it returns "dcba".

User Guide 339

Appendix B: Using the Expression Editor

Syntax
reverse ( string_exp )

right
Returns the rightmost integer_exp characters of string_exp.

Syntax
right ( string_exp, integer_exp )

round
Returns numeric_exp rounded to the nearest value integer_exp places right of the decimal point.

Syntax
round ( numeric_exp, integer_exp )

rtrim
Returns string_exp with trailing spaces removed.

Syntax
rtrim ( string_exp )

soundex
Returns a four-character soundex code for character strings that are composed of a contigous sequence of valid single- or double byte Roman letter.

Syntax
soundex ( string_exp )

space
Returns a string with the indicated number of single-byte space.

Syntax
space ( integer_exp )

str
Returns a string representation of numeric_exp. integer_exp1 is the length of the string returned. integer_exp2 is the number of decimal digits. length and decimal are optional(default length is 10; default decimal is 0.)

Syntax
str ( numeric_exp [ , integer_exp1 [ , integer_exp2 ] ] )

stuff
Delete integer_exp2 characters from string_exp1 at integer_exp1, and then insert string_exp2 into string_exp1 at integer_exp. To delete characters without inserting other characters, string_exp2 should be NULL, not " ", which indicates a single space.

Syntax
stuff ( string_exp1, integer_exp1, integer_exp2, string_exp2 )

substring
Returns the substring of string_exp that starts at position integer_exp1. integer_exp2 specifies the number of characters in the substring.

340

Framework Manager

Appendix B: Using the Expression Editor

Syntax
substring ( string_exp, integer_exp1, integer_exp2 )

to_unichar
Returns a unichar expression having the value of the integer_exp. If the integer_exp is in the range 0xD800..0xDFFF, the operation is aborted. If the integer_exp is in the range 0..0xFFFF, a single Unicode value is returned. If the integer_exp is in the range 0x10000..0x10FFFF, a surrogate pair is returned.

Syntax
to_unichar ( integer_exp )

uhighsurr
Returns 1 if the Unicode value at integer_exp is the high half of a surrogate pair (which should appear first in the pair). Otherwise, returns 0. This function allows you to write explicit code for surrogate handling. Particularly, if a substring starts on a Unicode character where uhighsurr() is true, extract a substring of at least 2 Unicode values, as substr() does not extract just 1. substr() does not extract half of a surrogate pair.

Syntax
uhighsurr ( string_exp, integer_exp )

ulowsurr
Returns 1 if the Unicode value at integer_exp is the low half of a surrogate pair (which should appear second in the pair). Otherwise, returns 0. This function allows you to explicitly code around the adjustments performed by substr(), stuff(), and right(). Particularly, if a substring ends on a Unicode value where ulowsurr() is true, extract a substring of 1 less characters (or 1 more), since substr() does not extract a string that contains an unmatched surrogate pair.

Syntax
ulowsurr ( string_exp, integer_exp )

uscalar
Returns the Unicode scalar value for the first Unicode character in string_exp. If the first character is not the high-order half of a surrogate pair, then the value is in the range 0..0xFFFF. If the first character is the high-order half of a surrogate pair, a second value must be a low-order half, and the return value is in the range 0x10000..0x10FFFF. If this function is called on a uchar_expr containing an unmatched surrogate half and the operation aborted.

Syntax
uscalar ( string_exp )

Sybase Math
log
Returns the natural logarithm of numeric_exp.

Syntax
log ( numeric_exp )

log10
Returns the base ten logarithm of numeric_exp.

Syntax
log10 ( numeric_exp )

User Guide 341

Appendix B: Using the Expression Editor

pi
Returns the constant value of pi as a floating point value.

Syntax
pi ()

sign
Returns an indicator of the sign of numeric_exp: +1 if numeric_exp is positive, 0 if zero or -1 if negative.

Syntax
sign ( numeric_exp )

Sybase Trigonometry
acos
Returns the arccosine of numeric_exp in radians. The arccosine is the angle whose cosine is numeric_exp.

Syntax
acos ( numeric_exp )

asin
Returns the arcsine of numeric_exp in radians. The arcsine is the angle whose sine is numeric_exp.

Syntax
asin ( numeric_exp )

atan
Returns the arctangent of numeric_exp in radians. The arctangent is the angle whose tangent is numeric_exp.

Syntax
atan ( numeric_exp )

tan
Returns the tangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
tan ( numeric_exp )

atn2
Returns the angle (in radians) whose tangent is (numeric_exp1/numeric_exp2).

Syntax
atn2 ( numeric_exp1, numeric_exp2 )

cos
Returns the cosine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cos ( numeric_exp )

342

Framework Manager

Appendix B: Using the Expression Editor

cot
Returns the cotangent of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
cot ( numeric_exp )

degrees
Returns numeric_exp radians converted to degrees.

Syntax
degrees ( numeric_exp )

radians
Return the degree equivalent of numeric_exp. Results are of the same type as numeric. For expressions of type numeric or decimal, the results have an internal precision of 77 and a scale equal to that of the numeric expression. When the money datatype is used, internal conversion to float may cause loss of precision.

Syntax
radians ( numeric_exp )

sin
Returns the sine of numeric_exp where numeric_exp is an angle expressed in radians.

Syntax
sin ( numeric_exp )

Member Summaries
This list contains predefined functions that return either a single summary value for a set of members or a different summary value for each member of a set of members.

aggregate
Returns a calculated value using the appropriate aggregation function, based on the aggregation type of the expression.

Syntax
aggregate aggregate aggregate aggregate ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

average
Returns the average value of selected data items.

Syntax
average average average average ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
average ( [Sales] for [Continent], [Country] )

Result: The average of [Sales] values for all the values of [Continent] and [Country].

User Guide 343

Appendix B: Using the Expression Editor

count
Returns the number of selected data items excluding NULL values.

Syntax
count count count count ( expr for [all] expr { , expr } ) ( expr for report ) ( expr within set set_expr { , expr } ) ( currentMeasure within set set_expr { , expr } )

Example
count ( [Sales] for [Continent], [Country] )

Result: The total number of entries under [Sales] for all the values of [Continent] and [Country].

maximum
Returns the maximum value of selected data items.

Syntax
maximum maximum maximum maximum ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
maximum ( [Sales] for [Continent], [Country] )

Result: The maximum value of [Sales] values for all the values of [Continent] and [Country].

median
Returns the median value of selected data items.

Syntax
median median median median ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
median ( [Sales] for [Continent], [Country] )

Result: The median value of [Sales] values for all the values of [Continent] and [Country].

minimum
Returns the minimum value of selected data items.

Syntax
minimum minimum minimum minimum ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
minimum ( [Sales] for [Continent], [Country] )

Result: The minimum value of [Sales] values for all the values of [Continent] and [Country].

percentage
Returns the percent of the total value for selected data items.

344

Framework Manager

Appendix B: Using the Expression Editor

Syntax
percentage ( numeric_expr set_expr {, set_expr } ) [ tuple member_expr {, member_expr } ] within set

Example
percentage ( [gosales].[sales measures].[quantity] tuple [gosales].[Staff].[].[department]->[West] within set children([gosales].[Staff].[].[Staff] )

percentile
Returns a value, on a scale of one hundred, that indicates the percent of a distribution that is equal to or below the selected data items.

Syntax
percentile ( numeric_expr set_expr {, set_expr } ) [ tuple member_expr {, member_expr } ] within set

quantile
Returns the rank of a value in terms of the specified range. It returns integers to represent any range of ranks, such as 1 (highest) to 100 (lowest).

Syntax
quantile ( numeric_expr, numeric_expr within set set_expr {, set_expr } ) [ tuple member_expr {, member_expr } ]

quartile
Returns the rank of a value, represented as integers from 1 (highest) to 4 (lowest), relative to a group of values.

Syntax
quartile ( numeric_expr [ tuple member_expr {, member_expr } ] within set set_expr {, set_expr } )

rank
Returns the rank value of selected data items. The type of ranking returned (Olympic, dense or serial) is data source dependent.

Syntax
rank ( numeric_expr [ tuple member_expr {, member_expr } ] within set set_expr {, set_expr } )

Example
rank ( [gosales].[sales measures].[quantity] tuple [gosales].[Staff].[].[department]->[West] within set children([gosales].[Staff].[].[Staff] )

standard-deviation
Returns the standard deviation of selected data items.

Syntax
standard-deviation standard-deviation standard-deviation standard-deviation ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

User Guide 345

Appendix B: Using the Expression Editor

Example
standard-deviation ( [ProductCost] for [Continent], [Country] )

Result: A value indicating the deviation between [ProductCost] and the average [ProductCost] for all the values of [Continent] and [Country].

total
Returns the total value of selected data items.

Syntax
total total total total ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
total ( [Sales] for [Continent], [Country] )

Result: The total value of [Sales] values for all the values of [Continent] and [Country].

variance
Returns the variance of selected data items.

Syntax
variance variance variance variance ( ( ( ( expr for expr { , expr } ) expr for report ) expr within set set_expr { , expr } ) currentMeasure within set set_expr { , expr } )

Example
variance ( [Product Cost] for [Continent], [Country] )

Result: A value indicating how widely [ProductCost] vary from the average [ProductCost] for all the values of [Continent] and [Country].

346

Framework Manager

Appendix C: Data Formatting Reference

This chapter contains definitions of data formatting properties found in Framework Manager. The definition for each formatting property is also shown when you select a property in the Data Format dialog box in Framework Manager. Note that for SAP BW metadata: any unit of meaure information that exists in SAP BW is automatically appended to the data value you cannot define a format for each currency in a multi-currency query subject.

Data Formatting Properties

The following is a list of properties available in the data formatting dialog.

Calendar Type
Specifies the type of calendar to be displayed. The date values will be mapped to the selected calendar before being formatted. The default value is inherited from the user's content language. Note that the Japanese Imperial setting is only applicable for Japanese languages.

Clock
Specifies whether to display the time in 12-hour or 24-hour format. The default value is inherited from the user's content language.

Currency
Specifies the currency to be used. The default currency symbol will be displayed unless the values of the Currency Display and Currency Symbol properties are changed. The default value is inherited from the model.

Currency Display
Specifies whether to display the international or local currency symbol. By default, the local currency symbol is displayed.

Currency Symbol
Specifies a character or characters to use as the symbol to identify the local currency. This symbol will precede the number and any sign, even if it is a leading sign. A space between the symbol and the numeric value can be specified by entering it in this property, after the symbol. The default value is inherited from the user's content language.

Currency Symbol Position

Specifies where the currency symbol will appear. If End is selected, any spaces that follow the character or characters in the Currency Symbol or International Currency Symbol properties will be rendered between the number and the symbol. The default value is inherited from the user's content language.

User Guide 347

Appendix C: Data Formatting Reference

Date Ordering
Specifies the order in which to display the day, month, and year. The default value is inherited from the user's content language.

Date Separator
Specifies the character to be displayed between the year, month, and day. The default value is inherited from the user's content language.

Date Style
Specifies the date style. The results rendered are determined by the language. Generally, Short uses only numbers, Medium uses some abbreviated words, Long uses complete words, and Full includes all available details.

Decimal Separator
Specifies the character that will separate non-decimal numbers from decimals. This property is ignored if no decimals are displayed. The default value is inherited from the user's content language.

Display AM / PM Symbols
Specifies whether to display the AM or PM symbols. The default value is inherited from the user's content language.

Display As Exponent
Specifies whether to render values in scientific notations, using exponents. If this property is set to No, no scientific notations will be used. If it is not specified, scientific notations will be used only when values exceed the maximum number of digits. The default value is inherited from the user's content language.

Display Days
Specifies whether to display the day. The format of the day can be controlled by selecting one of the specific formats. Selecting Julian means that the 3-digit day of the year will be displayed. The default value is inherited from the user's content language.

Display Eras
Specifies whether to display the era. The default value is inherited from the user's content language.

Display Hours
Specifies whether to display the hours. The default value is inherited from the user's content language.

Display Milliseconds
Specifies whether to display the milliseconds. The format of the milliseconds can be controlled by selecting one of the specific formats. This property is ignored if seconds are not displayed. The default value is inherited from the user's content language.

348

Framework Manager

Appendix C: Data Formatting Reference

Display Minutes
Specifies whether to display the minutes. The format of the minutes can be controlled by selecting one of the specific formats. The default value is inherited from the user's content language.

Display Months
Specifies whether to display the month. The format of the month can be controlled by selecting one of the specific formats. The default value is inherited from the user's content language.

Display Months
Specifies whether to display the month.

Display Seconds
Specifies whether to display the seconds. The format of the seconds can be controlled by selecting one of the specific formats. The default value is inherited from the user's content language.

Display Time Zone

Specifies whether to display the time zone. The default value is inherited from the user's content language.

Display Weekdays
Specifies whether to display the weekday. The format of the weekday can be controlled by selecting one of the specific formats. The default value is inherited from the user's content language.

Display Years
Specifies whether to display the year. The first two digits of the year, which indicate the century, can be controlled by selecting one of the associated property values. The default value is inherited from the user's content language.

Display Years
Specifies whether to display the year.

Exponent Symbol
Specifies the character to be displayed to identify exponents if the scientific notation is used. The symbol will be rendered after the number, separated by a space. The default value is inherited from the user's content language.

Group Size (digits)

Specifies the primary grouping size. If a value is specified it represents the number of digits to the left of the decimal point to be grouped together and separated by the thousands separator. The default value is inherited from the user's content language.

International Currency Symbol

Specifies a character or characters to use as a symbol to identify the international currency. This symbol will replace the currency symbol. A space between the symbol and the numeric value can be specified by entering it in this property, after the symbol. The default value is inherited from the user's content language.

User Guide 349

Appendix C: Data Formatting Reference

Mantissa (digits)
Specifies the number of digits to be displayed following the exponent symbol if the scientific notation is used.

Maximum No. of Digits

Specifies the maximum number of digits that can be displayed. If the maximum number of digits is not sufficient to display the value, a scientific notation will be used. The default value is inherited from the user's content language.

Minimum No. of Digits

Specifies the minimum number of digits that can be displayed. If the minimum number of digits is too high to display a value, the padding character will be used. The default value is inherited from the user's content language.

Missing Value Characters

Specifies the character or characters to be displayed when the value is missing. If no value is entered for this property, an empty string will be displayed.

Negative Pattern
Specifies a presentation format, based on patterns, for negative numbers. Some restrictions exist. The numerical part of the negative pattern is ignored. Only the suffix and the prefix are used. For example, in the pattern ABC#,##0.#EFG, ABC is the prefix, EFG is the suffix and #,##0.# is the numerical part of the pattern.

Negative Sign Position

Specifies where the negative sign will appear. The default value is inherited from the user's content language.

Negative Sign Symbol

Specifies how to display negative numbers. The default value is inherited from the user's content language.

No. of Decimal Places

Specifies the number of digits to be displayed to the right of the decimal point. If this property is not set the number of decimal places will vary depending on the number rendered.

Padding Character
Specifies the character that will be used to pad values that have fewer digits than the minimum number of digits. The default value is inherited from the user's content language.

Pattern
Specifies a presentation format that is based on patterns.

350

Framework Manager

Appendix C: Data Formatting Reference

Percentage Symbol
Specifies whether to display the values per hundred (percent) or per thousand. The symbol will be appended to the number and any trailing sign. A space between the numeric value and the symbol can be specified by entering it in this property, after the symbol. The default value is inherited from the user's content language.

Percent Scale (integer)

Scale to be applied to value after formatting. If omitted, no percent scale will be applied and the value will formatted according the normal decimal positioning associated with the percent (or per mille) symbol.

Scale
Specifies how many digits to move the decimal delimiter for formatting purposes. For example, move the decimal three spaces to present values in thousands. The default value is inherited from the database field.

Secondary Group Size (digits)

Specifies the secondary grouping size. If a value is specified it represents the number of digits to the left of the primary group that will be grouped together and separated by the thousands separator. If this property is left blank, the secondary grouping of digits is the same number as the primary group size, as specified by the Group Size (digits) property. The default value is inherited from the user's content language.

Thousands Separator
Specifies how to delimit digit groups, such as thousands. This property is only used if the Use Thousands Separator property is set to Yes. The default value is inherited from the user's content language.

Time Separator
Specifies the character to be displayed between the hour, minute, and second. The default value is inherited from the user's content language.

Time Style
Specifies the time style to be displayed. The exact results that will be rendered are determined by the language. Generally, Short means that the minimum details will be displayed, Long adds seconds, and Full means that all details are displayed, including the time zone. The default value is inherited from the user's content language.

Time Unit
Specifies the unit of measure of the value. This property will be ignored if any day or time components are shown. The default value is inherited from the user's content language.

Use Thousands Separator

Specifies whether the grouping delimiter will be applied as defined by the Group Size property. The default value is inherited from the user's content language.

User Guide 351

Appendix C: Data Formatting Reference

Zero Value Characters

Specifies the character or characters to be displayed when the value is zero (0). If no value is entered for this property, the Maximum No. of Digits property determines how many zero digits are displayed.

352

Framework Manager

Appendix D: Using Patterns to Format Data

You can format data so that it matches any pattern of text and numbers when default formats are not appropriate. For example, you can format dates to use full text including the era, or you can format them to only use numbers and show the last two digits of years to save space. Using symbols and patterns can provide similar results as basic data formatting tasks. For example, you can set how many digits appear after the decimal point. You can achieve these types of results with a pattern, or you can set the No. of Decimal Places property. Patterns allow flexibility for more complex requirements. Each supported content language code requires a specific set of symbols to be used in patterns. For each language code, there are two tables you will need; one for date and time symbols, and one for decimal symbols. The decimal symbols are the same for all locales, however, date and time symbols are grouped into six locale groups. Check the Date and Time Symbol section to see which locale group is used for your locale. To define patterns, open the Data Format dialog box, and edit the Pattern property for each format type. Use the symbols that are defined in the language code tables, and follow these guidelines.

Pattern Guidelines
When you define a pattern, the number of symbols you use affects how the data will be shown. There are different rules for text, numbers, and values that can take the form of text or numbers.

Text
You can specify whether text is produced in full or abbreviated form. Number of symbols 4 or more Less than 4

Meaning Full text form Abbreviated form

Example EEEE produces Monday EEE produces Mon

Numbers
The number of symbols you use in a pattern sets the minimum number of digits that are produced in a report. Numbers that have fewer digits than specified are zero-padded. For example, if you specify mm for minutes, and the database value is 6, the report will show 06. Note: The year value is handled differently. If you specify two symbols for year, the last two digits of the year value is produced. For example, yyyy produces 1997, and yy produces 97.

Text and Numbers

For values that can produce text or numbers, such as months, you can specify whether text or numbers are produced, and whether words are abbreviated. Number of symbols 3 or more

Meaning Text

Example MMMM produces January MMM produces Jan

User Guide 353

Appendix D: Using Patterns to Format Data

Number of symbols Less than 3

Meaning Numbers

Example MM produces 01 M produces 1

Date and Time Symbols

Locale ID af-za, en, en-au, en-be, en-bw, en-ca, en-gb, en-hk, en-ie, en-in, en-mt, en-nz, en-ph, en-sg, en-us, en-vi, en-za, fo-fo, gl-es, id, id-id, is, is-is, it, it-ch, it-it, kk-kz, ms, ms-bn, ms-my, nb-no, nl, nl-be, nl-nl, no, no-no, om-et, om-so, pl, pl-pl, pt, pt-br, pt-pt, so-dj, so-et, so-ke, so-so, sv, sv-fi, sv-se , sw-ke, sw-tz be-by, bg-bg, el, el-gr, fi, fi-fi, hr, hr-hr, hu, hu-hu, ja, ja-jp, ko, ko-kr, ro, ro-ro, ru, ru-ua, ru-ru, sh-yu, sk, sk-sk, sl-si, sq-al, sr-sp, th, tr, tr-tr, uk-ua, zh, zh-cn, zh-hk, zh-mo, zh-sg, zh-tw ca-es, cs, cs-cz, da, da-dk, es, es-ar, es-bo, es-cl, es-co, es-cr, es-do, es-ec, es-es, es-gt, es-hn, es-mx, es-ni, es-pa, es-pe, es-pr, es-py, es-sv, es-us, es-uy, es-ve, eu-es, mk-mk de, de-at, de-be, de-ch, de-de, de-lu fr, fr-be, fr-ca, fr-ch, fr-fr, fr-lu ga-ie Locale Group D Locale Group E Locale Group F Locale Group C Locale Group B Locale Group Locale Group A

354

Framework Manager

Appendix D: Using Patterns to Format Data

Locale Group A
Locales: af-za, en, en-au, en-be, en-bw, en-ca, en-gb, en-hk, en-ie, en-in, en-mt, en-nz, en-ph, en-sg, en-us, en-vi, en-za, fo-fo, gl-es, id, id-id, is, is-is, it, it-ch, it-it, kk-kz, ms, ms-bn, ms-my, nb-no, nl, nl-be, nl-nl, no, no-no, om-et, om-so, pl, pl-pl, pt, pt-br, pt-pt, so-dj, so-et, so-ke, so-so, sv, sv-fi, sv-se , sw-ke, sw-tz Meaning Era Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Time zone Escape used in text Single quote Symbol G y Y M w W D d F e E a k K h H m s S z " Presentation Text Number Number Text and number Number Number Number Number Number Number Text Text Number Number Number Number Number Number Number Text n/a n/a Example AD 1996 1996 July and 07 27 2 189 10 2 (2nd Wed in July) 2 Tuesday pm 24 0 12 0 30 55 978 Pacific Standard Time n/a

Locale Group B
Locales: be-by, bg-bg, el, el-gr, fi, fi-fi, hr, hr-hr, hu, hu-hu, ja, ja-jp, ko, ko-kr, ro, ro-ro, ru, ru-ua, ru-ru, sh-yu, sk, sk-sk, sl-si, sq-al, sr-sp, th, tr, tr-tr, uk-ua, zh, zh-cn, zh-hk, zh-mo, zh-sg, zh-tw Meaning Era Symbol G Presentation Text Example AD

User Guide 355

Appendix D: Using Patterns to Format Data Meaning Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Time zone Escape used in text Single quote Symbol a A n w W D j F e E x h K k H m s S z " Presentation Number Number Text and number Number Number Number Number Number Number Text Text Number Number Number Number Number Number Number Text n/a n/a Example 1996 1996 July and 07 27 2 189 10 2 (2nd Wed in July) 2 Tuesday pm 24 0 12 0 30 55 978 Pacific Standard Time n/a

Locale Group C
Locales: ca-es, cs, cs-cz, da, da-dk, es, es-ar, es-bo, es-cl, es-co, es-cr, es-do, es-ec, es-es, es-gt, es-hn, es-mx, es-ni, es-pa, es-pe, es-pr, es-py, es-sv, es-us, es-uy, es-ve, eu-es,mk-mk Meaning Era Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Symbol G u U M w W D Presentation Text Number Number Text and number Number Number Number Example AD 1996 1996 July and 07 27 2 189

356

Framework Manager

Appendix D: Using Patterns to Format Data Meaning Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Time zone Escape used in text Single quote Symbol t F e E a h K k H m s S z " Presentation Number Number Number Text Text Number Number Number Number Number Number Number Text n/a n/a Example 10 2 (2nd Wed in July) 2 Tuesday pm 24 0 12 0 30 55 978 Pacific Standard Time n/a

Locale Group D
Locales: de, de-at, de-be, de-ch, de-de, de-lu Meaning Era Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Symbol G j J M w W D t F e E a h Presentation Text Number Number Text and number Number Number Number Number Number Number Text Text Number Example AD 1996 1996 July and 07 27 2 189 10 2 (2nd Wed in July) 2 Tuesday pm 24

User Guide 357

Appendix D: Using Patterns to Format Data

Meaning Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Time zone Escape used in text Single quote

Symbol K k H m s S z "

Presentation Number Number Number Number Number Number Text n/a n/a

Example 0 12 0 30 55 978 Pacific Standard Time n/a

Locale Group E
Locales: fr, fr-be, fr-ca, fr-ch, fr-fr, fr-lu Meaning Era Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Symbol G a A M w W D j F e E x h K k H m s S Presentation Text Number Number Text and number Number Number Number Number Number Number Text Text Number Number Number Number Number Number Number Example AD 1996 1996 July and 07 27 2 189 10 2 (2nd Wed in July) 2 Tuesday pm 24 0 12 0 30 55 978

358

Framework Manager

Appendix D: Using Patterns to Format Data

Meaning Time zone Escape used in text Single quote

Symbol z "

Presentation Text n/a n/a

Example Pacific Standard Time n/a

Locale Group F
Locales: ga-ie Meaning Era Year Year (of 'Week of Year') Month in year Week in year Week in month Day in year Day in month Day of week in month Day of Week (1=first day) Day in week a.m. or p.m. marker Hour in day (1 to 24) Hour in a.m. or p.m. (0 to 11) Hour in a.m. or p.m. (1 to 12) Hour in day (0 to 23) Minute in hour Second in minute Millisecond Time zone Escape used in text Single quote Symbol R b B M t T l L F e E a u K k U n s S c " Presentation Text Number Number Text and number Number Number Number Number Number Number Text Text Number Number Number Number Number Number Number Text n/a n/a Example AD 1996 1996 July and 07 27 2 189 10 2 (2nd Wed in July) 2 Tuesday pm 24 0 12 0 30 55 978 Pacific Standard Time n/a

User Guide 359

Appendix D: Using Patterns to Format Data

Decimal Format Symbols

All Locales
Symbol 0 # . , E ; % Meaning A digit that is shown even if the value is zero. A digit that is suppressed if the value is zero. A placeholder for decimal separator. A placeholder for thousands grouping separator. Separates mantissa and exponent for exponential formats. Separates formats for positive numbers and formats for negative numbers. The default negative prefix. Multiplied by 100, as percentage. Multiplied by 1000, as per mille. The currency symbol. If this symbol is present in a pattern, the monetary decimal separator is used instead of the decimal separator. The international currency sign. It will be replaced by an international currency symbol. If it is present in a pattern, the monetary decimal separator is used instead of the decimal separator. X /u221E /uFFFD Other characters that can be used in the prefix or suffix. Used to quote special characters in a prefix or suffix. Infinity Symbol Not a Number Symbol

360

Framework Manager

Appendix E: Guidelines for Externalizing SAP BW Dimensions

Framework Manager provides the ability to externalize, or extract, data corresponding to a model. This functionality applies to all supported data sources, including SAP BW. However, special considerations must be given when externalizing models based on SAP BW metadata. This topic describes some of the different ways in which data may be extracted from SAP BW and the issues that you must address when doing so. When extracting data from SAP BW using Framework Manager, it is important to understand the distinction that Framework Manager makes between different types of dimensions. Each type of dimension exhibits a different behavior when it is externalized and can be fine-tuned before externalizing.

Extract Size
The Extract Size data source property within Framework Manager is used to control the amount of data retrieved from SAP BW at any one time. If this setting is negative, zero, or empty, a single query is issued to SAP BW to extract the characteristic data. If this setting is a positive value, Framework Manager issues multiple queries to SAP BW, each of which returns approximately the number of megabytes specified by the Extract Size property. This feature can reduce the overall size of the query result on the SAP BW server. Overall query execution may take longer, but for large characteristics, not using this feature may result in consumption of a user's allotted memory space on the SAP BW server. The entire data for a characteristic dimension will be in memory within Framework Manager prior to the production of an extract file. It is important that only the required query items be extracted from SAP BW to ensure that an extract does not fail due to memory allocation errors within Framework Manager. Model query subjects are extracted using the same mechanism by which queries are executed within Cognos 8. Therefore, the Extract Size property has no effect on the query execution.

Measure Dimensions
When extracting a measure dimension, you should create a model query subject containing the measures that you want. You should include the business key query item from each of the levels of each dimension, depending on the level of granularity that you are trying to achieve. For information about externalizing model query subjects, see "Framework Manager Considerations" (p. 363).

Characteristic Dimensions
Characteristic dimensions are externalized independent of the type of SAP BW data source, such as InfoCube or SAP BW Query. Framework Manager uses a single approach to externalize all dimensions that do not contain fact query items. In these cases, the extract size configuration setting is used to control the manner in which data is extracted from SAP BW. Note: Model query subjects are externalized in a different manner, regardless of whether they contain fact query items or not. For information about exernalizing model query subjects, see "Framework Manager Considerations" (p. 363).

User Guide 361

Appendix E: Guidelines for Externalizing SAP BW Dimensions

Key Figures Dimensions from an SAP BW InfoCube

When externalizing the key figures dimension from a model based on an InfoCube, Framework Manager uses exactly the same approach as used for externalizing model query subjects. For an InfoCube containing more than a few thousand transactions, externalizing an InfoCube directly from Framework Manager can easily exceed both time and memory limits on either the client or server. In such cases, it is highly recommended that an SAP BW Query be used as the basis for externalizing the SAP BW metadata.

Key Figures Dimensions from an SAP BW Query

Using a BEx query as the basis for externalizing key figures from an SAP BW data source is, in most cases, the best approach. By using a BEx variable to break the data of the key figure dimension into manageable sections, arbitrarily large volumes of transaction data can be extracted from SAP BW. Note, however, that this approach incurs some restrictions as to what can be extracted from SAP BW, and how it can be extracted. The remainder of this section describes how an SAP BW Query is used to extract data from SAP BW, including all known restrictions and limitations. For the remainder of this section, it is assumed that an SAP BW Query is being used as the basis for externalizing the data, not as the basis for reporting, and with the intent of exceeding the memory and time limitations associated with extracting data directly from an InfoCube.

SAP BW Query Requirements

First, it is not possible to externalize an arbitrary SAP BW Query. To be externalized, an SAP BW Query must adhere to the following restrictions: Only a single field can be shown. Showing something such as "key and text" will result in incorrect data. To change what appears for a characteristic, right-click the characteristic along the edge of the SAP BW Query and click Properties. In the Properties dialog box, set the Display As value to Key. It is strongly recommended that you use Key. To reduce data volumes, as well as the amount of aggregation performed by the SAP BW server, it is strongly recommended that summarization for all characteristics in the query be disabled in its property sheet. To disable summarization for a characteristic, right-click the characteristic along the edge of the SAP BW Query and click Properties. In the Properties dialog, set the Suppress Results Rows value to Always. If at least one characteristic in an InfoQuery is displayed as something other than Key, then summarization for all characteristics must be suppressed. The query must not contain the Currency/Unit characteristic. None of the characteristics may be assigned a display hierarchy, either explicitly or by a variable. If a characteristic is included in an SAP BW Query as a free characteristic, no values will appear for that characteristic in the key figures extract. A filter on a free characteristic acts as a filter on the data returned by SAP BW. It is an efficient mechanism for defining a subset of an InfoCube. Such a filter may also be applied to a characteristic along an axis of an SAP BW Query, in which case the filtered values appear in the key figures extract. All key figures in the SAP BW Query must be numeric. The values of each key figure should be in a single currency since currency information is not carried forward into a CSV extract. A variable should not be used to drive the assignment of a target currency. Include in the SAP BW Query only those characteristics which are to be extracted using Framework Manager. Including unnecessary characteristics increases the volume of data transferred from SAP BW, thus affecting performance.

362

Framework Manager

Appendix E: Guidelines for Externalizing SAP BW Dimensions

Guidelines and Constraints When Working with SAP BW Cubes

You must use CSV files when importing metadata from SAP BW cubes. For performance reasons, we recommend that you filter on geography, time periods, or some other dimension that limits the amount of data retrieved. Remember to apply your dimension filter to the related dimensions and their fact tables (measures). For more information, see "Create a Filter" (p. 174). Because SAP BW cubes are multidimensional, rollups are applied at the source. If you change the rollup type after importing the data into Transformer, your results will become invalid. Missing data or metadata that is out-of-scope for a particular measure may yield different results, depending on the context. You may see: NULL values # symbols REST_H Not assigned Because such duplicate tokens can cause problems in Transformer, in unique levels for example, we recommend that you assign filters to the dimension so that they do not appear in the imported data. Finally, remember to select only those query items needed to generate your filtered data.

Framework Manager Considerations

When extracting the measure dimension from an SAP BW Query, the Extract Size property of the data source is used to control the amount of data retrieved from the SAP BW server at one time. Model query subjects are externalized in a different manner, regardless of whether they contain fact query items or not. In this scenario, the setting has no affect on the SAP BW server, but it does limit the amount of memory allocated at any one time by Framework Manager to retrieve the data. It is important to realize that filters defined on the key figures dimension are not enforced when extracting data from an SAP BW Query. To obtain performance benefits of extracting data from an SAP BW Query, filters must be defined in an SAP BW Query. In addition, any calculations defined within the key figures dimension are ignored. These may be defined either within the SAP BW Query in BEx, or in a model query subject in Framework Manager. Each characteristic extracted must contain at least one query item from the lowest level of its hierarchy (if there is one) to provide linkage with the key figures extract. You should include the business key query item from each of the levels of each dimension, depending on the level of granularity that you are trying to achieve.

Use of Variables to Externalize Key Figures

The volume of transactions within an SAP BW Query is such that, in most cases, the use of a single query to extract the data from SAP BW will exceed the memory allocated to a user on an SAP BW server. In Framework Manager, you can use a single optional variable to extract fact data from an SAP BW Query in reasonably sized sections. To use this feature, one characteristic included in the SAP BW Query (but not included as a free characteristic) is assigned a variable that conforms to the following restrictions: It must be a single value. It must be optional. It must not have a default value. It can be defined on the characteristic or a presentation hierarchy. If an SAP BW Query contains such a variable and the key figures dimension is externalized, Framework Manager runs a query for each possible value associated with a variable. Thus, by choosing an appropriate characteristic, the key figures dimension can be extracted without exceeding the memory restrictions of either the client or server. Memory caches on the client and server are flushed after each query.

User Guide 363

Appendix E: Guidelines for Externalizing SAP BW Dimensions If a presentation hierarchy is used to drive the creation of extract sections, it is important that the values for a variable be obtained from a single level in the hierarchy, otherwise the extract will contain data summarized at different levels. To restrict the values for a variable to a single level of a hierarchy, edit the Level Restriction of the variable in Framework Manager. For example, using a value such as "2:2" indicates that only values from the second level of the hierarchy are to be used (level 0 is the root of a hierarchy). In the presence of an SAP BW Query with one such variable, the value of the variable is reset after each query. In an SAP BW Query contains anything more than a single variable, or one that is defined differently than described above, Framework Manager does not attempt to use a variable to break the extraction of the key figures dimension into smaller sections.

Workaround for Problems Encountered While Externalizing

When externalizing a data source from Framework Manager, you may encounter an authentication error if the model is published to Content Manager externalizing the data takes longer to perform than the timeout period assigned to passports within Cognos Configuration Users are not prompted to re-enter their authentication credentials. If an error occurs, the externalized data is still complete and valid. However, if the modeler chooses to actually publish the model, the modeler must re-authenticate and re-publish the model, but without externalizing the data. Another solution is to publish the model to the network, in which case the authentication error does not occur.

Building PowerCubes from SAP BW Data

You can build Cognos PowerCubes from SAP BW data. There are guidelines to consider for both Framework Manager and Transformer.

Framework Manager Guidelines

When externalizing data for the purpose of creating one or more PowerCubes, keep these considerations in mind. The extract of each characteristic must have a common key query item that is equivalent to a surrogate key query item in the key figures extract. For an extract based on an SAP BW Query, it is strongly recommended that all characteristics be displayed as Key in the SAP BW Query. If a characteristic does not have a presentation hierarchy, or a new one is desired, extract one or more query items that can form the basis for levels in a hierarchy. During the import of SAP BW metadata into a model that is to be used for the purpose of extracting data, it is desirable to limit the model to only those query items that are absolutely required to build a PowerCube. This will have the effect of improving data extract performance. A practical limit for PowerCubes is 1,000,000 categories (values) for a dimension (characteristic).

Transformer Guidelines
When using the SAP BW data that you extracted from Framework Manager, keep these considerations in mind. Using the model wizard in Transformer, insert a data source of type Delimited-Field Text With Column Titles and start by selecting the fact table. Do not run auto-design. Drag all the key figure columns from the Data Sources pane into the Measures pane. Ensure that the aggregation rule for each measure is correctly defined within Transformer to align as closely as possible with the aggregation rule defined in SAP BW. It is recommended that the storage type for all measures be set to 64-bit floating point. 364 Framework Manager

Appendix E: Guidelines for Externalizing SAP BW Dimensions Using the date wizard, select a query item that will provide the dates for the PowerCube. Note that the dates for the PowerCube can be derived entirely from the transaction data. Insert the various CSV files corresponding to the characteristics that were externalized using Framework Manager. Each CSV file contains a column that corresponds to a column in the key figures CSV file. By right-clicking the various columns and editing the column properties, ensure the columns that provide the linkage between a characteristic and the key figures have the same name. For example, if a key figure column is named Customer and the corresponding column in the customer CSV file is named Customer - Key, then the name of the column in the key figures CSV file can be changed to Customer - Key. For each characteristic, create a new dimension, using the key columns, or other attributes of a characteristic, to drive the levels of the dimension. For each level, ensure that the properties for the label, short name, and description are assigned source columns, if applicable. For the root level of each characteristic (dimension), ensure it is marked as unique. SAP BW presentation hierarchies may contain ragged paths, typically in association with the "not assigned" and "#" nodes in the hierarchy. The gaps in these hierarchies produce blanks at the associated level in the Transformer hierarchy. In Transformer, it is possible to define the text that should be used for blanks (the default text is "<blank>"). A best practice is to define a more appropriate text for blank entries for all such levels.

User Guide 365

Appendix E: Guidelines for Externalizing SAP BW Dimensions

366

Framework Manager

Appendix F: Reserved Words

You must ensure that the names of data sources, tables, and columns do not use names reserved by Cognos 8. If you must use a reserved word, enclose the word in quotes in the SQL specification. For example, select Orderdate, "Timezone". Cognos 8 reserves these words: _cursor _local _rowset abs all and any as asc at avg between bigint bit_length boolean both by call case cast ceil ceiling char char_length character character_length coalesce count create cross cube cume_dist

User Guide 367

Appendix F: Reserved Words current current_date current_time current_timestamp cursor date day dbkey dec decimal declare delete dense_rank desc distinct double else end escape except exists exp extract false filename filter first first_value float floor following for from full group grouping having hour in inner insert int integer 368 Framework Manager

Appendix F: Reserved Words intersect interval into is join last last_value leading left like ln local localtime localtimestamp lower max min minute mod month national natural nchar no not ntile null nullif nulls numeric nvarchar octet_length of on or order others out outer over partition perc percent_rank User Guide 369

Appendix F: Reserved Words percentile percentile_cont percentile_disc position power preceding precision prefilter qualify range rank ratio_to_report ravg rcount rdiff real recursive returning right rmax rmin rollup row row_number rows rsum scroll second select set sets smallint snapshot some sqrt stddev stddev_pop stddev_samp substring sum table tertile then 370 Framework Manager

Appendix F: Reserved Words time timestamp timezone_hour timezone_minute to trailing trim true unbounded union unknown updatable update upper user using values var_pop var_samp varchar variance varying when where window with within without xavg xcount xfirst xlast xmax xmin xmovingavg xmovingsum xntile xperc xrank xratio xstddev xstddev_pop xsum User Guide 371

Appendix F: Reserved Words xtertile xvariance xvariance_pop year zone

372

Framework Manager

Appendix G: XML Data Types

You can import XML as a tabular data source in Framework Manager. The following data types are supported when importing from XML into Framework Manager. anyURI boolean byte date dateTime decimal double ENTITIES ENTITY float ID IDREF IDREFS int integer language long Name NCName negativeInteger NMTOKEN NMTOKENS nonNegativeInteger NonPositiveInteger normalizedString NOTATION positiveInteger QName short string time token unsignedLong unsignedInt unsignedShort unsignedByte

The following data types are not supported.. unknown duration gYearMonth gYear gMonthDay gDay gMonth hexBinary base64Binary

User Guide 373

Appendix G: XML Data Types

374

Framework Manager

Glossary
access permissions
Rules defining the access rights to resources. Access permissions can be granted to any combination of namespaces, groups, or users. Examples of resources are reports and folders.

alias
In modeling and database terminology, a secondary name for a database table. Aliases are used to create a distinct reference to the table in the model, so that self-joins can be created or ambiguous query paths can be resolved.

attribute
In relational models, a query item that is not a measure or identifier. When a query item is an attribute, it is not intended to be aggregated, or used for grouping or generating prompt pick lists. In dimensional models, attributes provide qualitative information about members of a level in a dimension. For example, the Store level within the Retailer dimension might have properties such as "address" or "retail space." In general, dimensional attributes do not have measure values or rollups associated with them, but are used to locate or filter members.

calculated member
A member of a dimension whose measure values are not stored but are calculated at run time using an expression.

cardinality
For OLAP data sources, cardinality is the number of members in a hierarchy. The cardinality property for a hierarchy is used to assign solve orders to expressions. For relational data sources, cardinality indicates the nature of the relationship between two query subjects, query items, or other model objects.

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.

data source
A relational database, dimensional cube, file, or other physical data store that can be accessed though Cognos 8.

User Guide 375

dimension
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.

governor
A set of rules to limit user activities, such as the execution of reports, that either take too long, or consume too many resources.

hierarchy
A hierarchy represents a collection of dimensional members organized into a tree structure, with each member having one or more parent members and an arbitrary number of child members. The root of a hierarchy has no parent, and leaf members of a hierarchy have no children.

level
A level is a set of members that have common attributes. For example, a geographical dimension might contain levels for country, region, and city. Levels are used to define the structure of hierarchies in a dimension.

locale
A code that is used to set the language or dialect used for browsers, report text, and so on; and the regional preferences, such as formats for time, date, money, money expressions, and time of day. For Cognos products, you can specify a locale for the product interface (product locale) and for the data in the report (content locale).

measure
A performance indicator that is quantifiable and used to determine how well a business is operating. For most business purposes the aggregate values of a measure are more useful than individual values. For example, measures can be Revenue, Revenue/Employee, and Profit Margin %. In relational modeling, this is also called a "fact."

member
A member is a unique item within a level. For example, Camping Equipment and Golf Equipment are members of the Product Line level. See also member unique name. A name that uniquely identifies a member from either an OLAP data source or a dimensionally modeled relational source. A Member Unique Name is a path of member names, one from each level in a hierarchy, defining the exact location of the member. For example, Geography.Europe.France.Paris uniquely identifies Paris, France from other instances of Paris in the City level.

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.

376

Framework Manager

A model, called 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.

model segment
A part of a Framework Manager project that is a shortcut to a second project. Segments can be parameter maps, data sources, namespaces, or folders. You must make any changes in the source project, not in the segment. You use segments to simplify model maintenance or to facilitate multi-user modeling. How you use segments does not affect the packages that you publish to Cognos 8.

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.

normalization
An industry standard approach to the design of relational databases, based on primary and foreign keys, aimed at minimizing redundancy and optimizing update operations.

package
A subset of a model, which can be the whole model, to be made available to the Cognos 8 server. For Metric Studio users, see metric package.

project
In Framework Manager, a set of models, packages, and related information for administration, and for sharing model information. In Metric Studio, a project is a task or set of tasks undertaken by a team and monitored on a scorecard. A project tracks the dates, resources and status of the project. In Metric Designer, a project is a group of extracts. Each extract contains the metadata that is used to populate the Metric Studio data store or to create applications.

publish
To expose all or part of a Framework Manager model via a package to the Cognos 8 server, so that Cognos BI Users can use it to create reports and other content.

query item
A representation of a column of data in a data source. It contains a reference to a database column, a reference to another query item, or a calculation. Query items may appear in a model or in a report.

User Guide 377

query subject
One of the types of objects inside a model. A query subject can be defined as a collection of references to items of other query subjects, or expressed as an SQL expression that represents selected query items. These query items will be retrieved from objects such as tables, synonyms, views, and so on. Query subjects contain query items.

378

Framework Manager

Index
A
A-C, 282 access permissions definition, 375 accessing data source connections, 64 secured InfoCube, 31 action logging, 52, 53 action logs running in batch mode, 53 adding business rules for relational metadata, 120 business rules for SAP BW metadata, 171 data source functions, 69 function sets, 69 groups, 199 items to query subjects, 91 languages for relational metadata, 108 languages for SAP BW metadata, 162 languages to packages, 204 metadata security, 203 object security, 202 roles, 199 security, 203 users, 199 additive, 116, 168 administrative access, 203 aggregate rollups, 68 aggregation regenerating values for SAP BW metadata, 169 rules for relational metadata, 113, 114, 115, 116 rules for SAP BW metadata, 166, 167, 168 SAP BW metadata, 190 types, 168 types for relational metadata, 116 aliases definition, 375 using with parameters, 125, 183 ambiguous objects, 244 ambiguous paths, 138 Analysis Studio and sparse data, 76 analyzing problems, 13 publishing impact on packages, 208 applying filters for relational metadata, 123 filters for SAP BW metadata, 175 Architect XML files importing, 32 As View SQL, 106 model query subjects, 107 attributes, 78, 79, 83, 145, 149, 231, 234 definition, 375 automatic aggregation types relational metadata, 115 SAP BW metadata, 167, 168

B
balanced hierarchies, 82, 145, 187 BIT datatype, 257 BLOBS, 253 BLOBs, 194 Block Functions, 279 Business Date/Time Functions, 276 business layer, See business view Business Objects expressions, 256 business rules for relational metadata, 120 calculations, 120 filters, 122 macros, 129 parameter maps, 125 parameters, 129 prompts, 125 session parameters, 128 business rules for SAP BW metadata, 171 calculations, 172 filters, 174 business view for relational metadata, 73, 136 folders, 141 namespaces, 141 shortcuts, 140, 141 shortcuts and relationships, 140 business view for SAP BW metadata, 143, 185 folders, 186 namespaces, 186 query item folders, 186 shortcuts, 185 shortcuts and dimensions, 186

C
cached data reusing, 196 calculated aggregations relational metadata, 114 calculated key figures, 30 calculated members definition, 375 calculations creating for relational metadata, 120 creating for SAP BW metadata, 172 security, 202 troubleshooting, 255 validating, 255 Calendar Type, 347

User Guide 379

Index
cardinality 1-1, 240 1-n, 240 checking, 213 data source, 74, 214 definition, 375 dimensions and facts, 215 notation, 75 queries, 75, 214 redefining, 76 rules, 75, 214 types, 75, 214 catalog, 67 changing type of SQL, 102 changing packages analyzing the effects, 208 characteristic dimensions externalizing, 361 checking projects, 191 relationships, 73 checking in projects, 50 checking out projects, 50 choosing query processing, 69 circular joins, 247 clearing object security, 202 CLOBS, 253 Clock, 347 Cognos 8 models importing, 32 Cognos PowerCubes as data sources, 62 publishing, 208 Cognos SQL, 104 collation sequences, 59 columns with BIT datatype are summarized in Query Studio reports, 257 comments adding to SQL, 102 Common Functions, 282, 295 Common Warehouse Metamodel, 39 comparing tables, 96, 157 Composite data sources connecting to, 64 conditional query subjects, 125, 183 configuring CVS repository connections, 49 conformed dimensions creating, 96, 157 multiple facts, 238, 241 removing, 152 conformed query subjects, 31 conformed star schema groups, 228 conforming dimensions, 151 connecting to data sources, 59 connecting to multiple PowerCubes, 59 connections repositories, 48 connections between dimensions, 86, 152 query subjects, 96, 156 Constants, 274 Constructs, 275 content manager data source, 67 Context Explorer, 86, 96, 152, 156 controlling access, 199 SQL generation, 194 converting measure to query items, 84 measures into query items, 85 query items into measures, 119 query subjects into dimensions, 101 regular dimensions, 88 copying projects, 45 copyright, 2 Create, 187 Create a Measure, 187 creating, 39 calculations for relational metadata, 120 calculations for SAP BW metadata, 172 CVS repository connections, 49 data source connections, 64 dimensions for relational metadata, 78, 79, 83, 145, 149 filters for relational metadata, 122 filters for SAP BW metadata, 174 folders for relational metadata, 141 folders for SAP BW metadata, 186 links, 44 measure dimensions, 217 measure dimensions for relational metadata, 84 measure folders for relational metadata, 142 measure folders for SAP BW metadata, 187 namespaces, 28 namespaces for relational metadata, 141 namespaces for SAP BW metadata, 186 packages, 197 parameter maps for relational metadata, 125 parameter maps for SAP BW metadata, 183 projects, 24 prompts with query macros, 132 query item folders for relational metadata, 142 query item folders for SAP BW metadata, 186 query sets, 96 query sets for SAP BW metadata, 157 query subjects for relational metadata, 90 query subjects for SAP BW metadata, 155 regular dimensions, 217 regular dimensions for relational metadata, 79, 85 relationship shortcuts for relational metadata, 77 relationships for relational metadata, 77 repositories, 48 segments, 43 star schema groups, 228 Visual SourceSafe database connections, 48 Visual SourceSafe repository connections, 48 cross-fact queries, 215

380

Framework Manager

Index
cross-product joins, 194 csv files, 205, 207 CSVIdentityName function, 201 CSVIdentityNameList function, 201 cubes, 67 definition, 375 curly brackets, 129 Currency, 347 currency format type, 117, 169 SAP BW, 162 troubleshooting, 255 unable to see, 255 Currency Display, 347 Currency Symbol, 347 Currency Symbol Position, 347 custom relationship expressions, 76 CVS repository connections configuring, 49 creating, 49 CWM, See Common Warehouse Metamodel data sources (cont'd) Cognos 8 models, 32 connecting, 59 connecting to, 59 connection levels, 60 DecisionStream, 32 definition, 375 ERwin, 35 IBM DB2 Cube Views, 35 Impromptu XML files, 32 modifying properties, 67 multilingual, 41 OMG CWM, 35 Oracle Designer, 35 properties, 69 relational databases, 29 SAP BW, 30 third-party metadata sources, 35 XML files, 38 data types, 230 data warehouse relationships, 73 database connections, See data source connections database functions vendor-specific, 69 database layer, See import view database only, 69 databases importing, 29 sorting, 59 datatypes graphic, 257 date format type, 117, 169 prompts, 118, 170 Date Ordering, 348 Date Separator, 348 Date Style, 348 DB2, 295 DB2 Cast, 303 DB2 Math, 304 DB2 Trigonometry, 305 Decimal Separator, 348 DecisionStream importing, 32 deconforming SAP BW dimensions, 152 default data set setting, 39 defining function sets, 69 languages for relational metadata, 108 languages for SAP BW metadata, 162 prompt controls, 118 prompt controls for SAP BW metadata, 170 deleting projects, 46 detecting relationships, 78 determinants, 212 cardinality, 74, 214 converting from dimension information, 234 defining, 222

D
data formatting for relational metadata, 117 formatting for SAP BW metadata, 169 security, 199, 200 using multilingual, 40 data integrity maintaining, 59 Data Query Stored Procedure Updates the Data Source, 253 data source adding functions, 69 data source connections, 59, 64 accessing, 64 Cognos PowerCubes, 62 Composite Software, 64 creating, 64 isolation levels, 60 Microsoft Analysis Services, 63 Microsoft SQL Server, 63 MS SQL, 64 ODBC, 64 OLAP cubes, 62 testing, 66 using network paths, 66 XML, 63 data source dimensions, 223 data source functions adding, 69 data source properties, 148 data source query subjects, 89 definition, 14 determinants, 92 modifying when relational, 94 using parameters, 129 data source query subjects for relational metadata adding items, 91 modifying, 91 data sources Architect XML files, 32

User Guide 381

Index
determinants (cont'd) reviewing, 235 specifying, 92 SQL generation, 93 upgrading to, 230 D-G, 286 Diagram tab, 18 diagrams, 15 viewing, 18 different languages troubleshooting, 253 dimension information, 231, 234 dimension map, 78, 79, 83, 145, 149 Dimension Map tab, 18 dimensional models star schemas, 137 dimensional queries, 237 multiple facts and grains, 238, 241 single fact, 237 dimensionally modeling relational metadata, 213 dimensions ambiguous, 244 converting from query subjects, 231 creating, 18 data source, 223 defining, 222 definition, 14, 376 exploring, 18 hierarchies, 227 identifying, 215 measure, 212, 217, 222 model, 223 modifying, 18 properties, 19 query subjects, 223 regular, 212, 217, 222, 223 reviewing, 233 role-playing, 218 scope relationships, 213 searching, 19 star schema groups, 228 upgrading to, 230 dimensions for relational metadata, 78, 137 balanced hierarchies, 82 converting, 88 converting from query subjects, 101 dimension map, 78, 79, 83, 145, 149 exploring, 86 hierarchies, 81 keys, 83 levels, 81, 82 measure, 84 merging, 85 modifying, 88 ragged hierarchies, 82 regular, 79 roles, 83 scope relationships, 85 shortcuts, 141 snowflaked, 140 testing, 86 unbalanced hierarchies, 82 dimensions for SAP BW metadata, 144 balanced hierarchies, 145 conforming, 151 deconforming, 152 exploring, 152 hierarchies, 145 key figures, 150 keys, 149 levels, 145, 148 modifying, 154 network hierarchies, 147 ragged hierarchies, 146 regular, 145 roles, 149 shortcuts, 186 testing, 152 unbalanced hierarchies, 146 Display AM / PM Symbols, 348 Display As Exponent, 348 Display Days, 348 Display Eras, 348 Display Hours, 348 Display Milliseconds, 348 Display Minutes, 349 Display Months, 349 Display Seconds, 349 Display Time Zone, 349 Display Weekdays, 349 Display Years, 349 document version, 2 double quotation marks, 129 double-counting, 212, 215, 240, 244 drop-down list prompts, 118, 170 duplicate object names importing, 29

E
editing SQL, 102 embedded files, 205, 207 embedded strings, 129 environment Framework Manager, 14 error messages QE-DEF-0177, 257 UDA-SQL-0107, 257 UDA-SQL-0114, 257 Error with Some Graphic Items, 257 error with summarization, 257 ERWin stored procedures troubleshooting, 254 escape symbol, 129 evaluating relational query subjects, 100 SAP BW query subjects, 161 Event Studio data query updates database, 253 examples for relational metadata in_range function, 122 moving models, 127

382

Framework Manager

Index
examples for relational metadata (cont'd) multilingual modeling, 110 prompts, 133-136 examples for SAP BW metadata in_range function, 174 multilingual modeling, 164 Explorer tab, 18 exploring dimensions, 78, 79, 83, 86, 145, 149, 152 object-based security, 204 objects, 18 packages, 204 query subjects, 96, 156 roles, 204 Exponent Symbol, 349 exporting metadata as CWM files, 39 translation tables, 109 translation tables for SAP BW metadata, 163 Expression Editor function sets, 69 expression syntax, 253 troubleshooting, 253, 257 expressions custom, 76 using prompts, 125 using prompts for SAP BW metadata, 176 Expressions Imported from Business Objects Metadata Source Do Not Work, 256 externalizing characteristic dimensions, 361 Framework Manager requirements, 363 InfoCube key figures, 362 measure dimensions, 361 model query subjects, 361 query subjects, 205, 207 SAP BW Query key figures, 362, 363 SAP BW Query requirements, 362 troubleshooting, 254 externalizing query subjects, 361 filters for relational metadata (cont'd) multiple query items, 119 multiple query subjects, 100 filters for SAP BW metadata applying, 175 creating, 174 determining usage, 175 expressions, 190 modifying, 174 multiple dimensions, 154 multiple query items, 171 multiple query subjects, 161 finding objects in the model, 47 folders creating, 141, 142 using shortcuts, 140 folders for SAP BW metadata creating, 186, 187 using shortcuts, 185 foreign keys, 78 format types currency, 117, 169 date, 117, 169 text, 117, 169 formatting data for relational metadata, 117 data for SAP BW metadata, 169 Framework Manager not a trusted site, 255 processing SAP BW query, 253 project, 23 script error when testing query subjects, 255 unable to run stored procedures, 254 unable to view result of stored procedure, 253 full outer joins, 74, 214 function set ID, 67 function sets adding, 69, 197 defining, 69 functions project, 69 supported by SAP BW, 173 functions lists packages, 256 troubleshooting, 256

F
fact tables, 84, 137 fact-less query, 228 facts, 212, 217 ambiguous, 244 identifying, 215 FDS errors after upgrading, 256 file-based data sources recommendation, 66 filters mandatory, 122 optional, 122 security, 200, 202 filters for relational metadata applying to query subjects, 123 creating, 122 determining usage, 123 modifying, 122 multiple dimensions, 88

G
generating relationships, 78 governors allow usage of local cache, 196 definition, 376 setting, 194 granularity, 221 GRAPHIC datatype, 257 graphic items, 257 Group Size (digits), 349 groups adding, 199

User Guide 383

Index

H
hierarchies, 78, 79, 81, 83, 145, 149, 212, 222, 223, 231, 234 balanced, 82, 145, 187 definition, 376 multiple, 227 network, 82, 147 ragged, 82, 146, 188 SAP BW, 147 sort order, 189 unbalanced, 82, 146, 188 versioned, 148 history viewing, 51 H-L, 287, 288

installing language packs, 255 International Currency Symbol, 349 IQD files, 205, 207 troubleshooting, 254 isolation levels, 60

J
joins, 73 circular, 247 full outer, 74, 214 inner, 75, 78 key and index information, 255 modifying, 76 outer, 75, 76, 255 Joins That Contradict Index and Key Information, 255

I
identifiers unique, 212 imensions for relational metadata network hierarchies, 82 import view relational metadata, 73 SAP BW metadata, 143 imported metadata checking, 213 importing Architect XML files, 32 Cognos 8 models, 32 databases, 29 DecisionStream, 32 duplicate object names, 29 Impromptu XML files, 32 metadata from XML files, 38 metadata into Framework Manager, 28 relational metadata, 78 relationships, 73 SAP BW hierarchies, 147 SAP BW metadata, 30 third-party data sources, 35 translation tables for relational metadata, 109 translation tables for SAP BW metadata, 163 Impromptu Query Definition files, 205, 207 Impromptu XML files importing, 32 improving performance reusing cached data, 196 in_range function, 122, 174 indexes relationships, 255 InfoCube permissions for accessing metadata, 30 InfoCube key figures externalizing, 362 Informix, 306 functions, 90 stored procedures, 90 Informix Math, 309 Informix Trigonometry, 309 inner joins, 75, 78

K
key figures, 30 key figures dimensions for SAP BW metadata, 150 keys, 78, 79, 83, 145, 149, 214, 231, 234 cardinality, 74 relationships, 255

L
language packs installing, 255 languages adding for relational metadata, 108 defining for relational metadata, 108 defining for SAP BW metadata, 162 expression syntax, 253 setting up multilingual environment, 40 specifying for packages, 204 levels, 78, 79, 81, 82, 83, 145, 148, 149, 212, 231, 234 definition, 376 limited local, 69 linked projects recommendations, 43 synchronizing, 56 links creating, 44 literal strings, 129 local query processing rollup processing, 68 locales definition, 376 locales, See also languages log files, 52 play back, 52 logging on to MS SQL, 64

M
Macro Functions, 280 macros prompts, 129 troubleshooting, 254

384

Framework Manager

Index
macros (cont'd) using, 129 main projects, 43 maintaining data integrity, 59 managing packages, 202, 203, 204 projects, 45, 52 mandatory cardinality, 75, 214 mandatory prompts, 132 Mantissa (digits), 350 many-to-many relationships, 74, 214 many-to-one relationships, 74 Map Manager configuring for multilingual, 41 labels, 41 mapping parameter values for relational metadata, 125 parameter values for SAP BW metadata, 183 SAP BW objects to Framework Manager, 143 maps Map Manager, 41 master-detail tables, 217 maximum cardinality, 75, 214 Maximum No. of Digits, 350 measure dimensions, 212 creating, 217 defining, 222 externalizing from SAP BW, 361 role-playing, 218 measure dimensions for relational metadata creating, 84 exploring, 86 scope relationships, 85 measure dimensions for SAP BW metadata exploring, 152 measure folders, 142, 187 measures converting, 85, 119 converting to query items, 84 definition, 376 Member Summaries, 343 members definition, 376 merging query subjects, relational, 95 query subjects, SAP BW, 156 regular dimensions, relational, 85 metadata exporting, 39 importing, 28 merging, 95, 156 publishing, 191 relational, 73 SAP BW, 143 security, 199, 203 Microsoft SQL server and logon, 64 Microsoft Analysis Services data sources connecting to, 63 Microsoft SQL Server data sources connecting to, 63 Minimized SQL, 106 model query subjects, 107 minimum cardinality, 75, 214 Minimum No. of Digits, 350 Missing Value Characters, 350 model dimensions, 223 model objects, 15 using parameters, 125, 183 viewing, 15 model portability, 194 model query subjects definition, 14 externalizing, 361 security, 202 model query subjects for relational metadata, 89 adding items, 91 creating, 90 creating from existing objects, 95 determinants, 92 modifying, 91 SQL type, 107 model query subjects for SAP BW metadata, 155 creating, 155 creating from existing objects, 156 model segments definition, 377 model versions updating, 207 modeling data sources, 41 distributed models, 42 long time to process InfoQuery, 253 main projects, 42 multilingual, 41 multiuser, 42 required currency not displayed, 255 script error when testing query subjects, 255 security error messages in Windows 2003 Server Edition, 255 unable to run stored procedures from ERWin, 254 unable to view result of stored procedure, 253 models, 14 definition, 14, 376 preparing relational, 73 preparing SAP BW metadata, 143 publishing, 191 repairing, 231 reviewing, 230 sample, 20 troubleshooting, 256 upgrading, 25, 230, 256 verifying, 191 versioning, 207 Modifying, 113, 166 modifying conformed dimension, 152 dimensions for SAP BW metadata, 154 filters for relational metadata, 122 filters for SAP BW metadata, 174 multiple SAP BW query subjects, 161 package access, 203 package administrative access, 203

User Guide 385

Index
modifying (cont'd) packages, 197 properties, 19 query item properties, 119, 171 query items for relational metadata, 111 query items for SAP BW metadata, 164 query subjects, 91 query subjects for SAP BW metadata, 161 relational data source query subjects, 94 relational dimensions, 88 relational query subjects, 100 relationships, 76 session parameters, 128, 184 SQL at runtime, 132 stored procedure query subjects, 94 moving projects, 46 relational models, 127 M-Q, 290 MS Access, 310 MS Access Cast, 314 MS Access Math, 315 MS Access Trigonometry, 315 multidimensional query subjects, 155 multilingual data sources, 41 data, using, 40 Map Manager, 41 multilingual modeling example for relational metadata, 110 example for SAP BW, 164 packages, 204 parameters, 108 relational metadata, 107 SAP BW metadata, 161 multilingual reporting environment setting up, 40 multiple data sets, 38 setting default data set, 39 multiple data source connections using, 59, 64 multiple hierarchies, 227 multiple users modeling, 42 multiple valid relationships, 218 multiple-fact queries, 223, 238, 241 multiple-grain queries, 223, 238, 241 multiuser modeling, 42 Negative Sign Position, 350 Negative Sign Symbol, 350 nested parameters, 125, 183 network hierarchies, 82, 147 No. of Decimal Places, 350 non-additive, 116, 168 normalization definition, 377 notations, 74, 75 number sign reserved for macros, 129

O
object security, 199 adding, 202 calculations, 202 exploring, 204 filters, 202 model query subjects, 202 removing, 202 shortcuts, 202 objects exploring, 18 naming conventions, 19 properties, 19 searching, 19 searching for, 47 unique identifiers, 19 ODBC data source, 64 OLAP cubes as datasources, 62 OLAP data sources publishing, 208 one-to-many relationships, 74, 215, 240 one-to-one relationships, 74, 215, 240 opening projects, 25 Operators, 259 optional cardinality, 75, 214 optional prompts, 132 optional relationships, 74, 214 Oracle, 316 Oracle Cast, 321 Oracle Math, 321 Oracle Trigonometry, 321 organizing models, 136, 185 outer joins, 75, 78, 194, 255 Analysis Studio, 76 full, 74, 214 SAP BW metadata, 189

N
namespaces, 14 creating, 28 creating for relational metadata, 141 creating for SAP BW metadata, 186 definition, 14, 377 naming conventions objects, 19 native metadata, 62 native SQL, 105 Negative Pattern, 350

P
package administrative access modifying, 203 packages, 14 access, 203 adding security, 203 administrative access, 203 analyzing changes, 208 creating, 197

386

Framework Manager

Index
packages (cont'd) definition, 14, 377 exploring, 204 functions lists, 256 managing, 202, 203, 204 modifying, 197 multilingual support, 204 publishing, 207 security, 199 troubleshooting functions lists, 256 viewing inclusion, 204 Padding Character, 350 parameter maps for relational metadata, 125 creating, 125 using as lookup tables, 107 parameter maps for SAP BW metadata, 183 creating, 183 currency, 162 using as lookup tables, 161 parameters for relational metadata creating, 125 data source query subjects, 129 model objects, 125 multilingual modeling, 108 nested, 125 session, 128 using, 129 using aliases, 125 parameters for SAP BW metadata creating, 183 currency, 162 maps, 183 session, 184 pass-through SQL, 105 Pattern, 350 Percent Scale (integer), 351 Percentage Symbol, 351 performance tuning query processing, 69 performance, optimizing for SAP BW, 187 physical layer, See import view play back action logs, 53 plus operator, 129 PowerCubes building from SAP BW data, 364 connecting to multiple data sources, 59 Framework Manager guidelines, 364 Transformer guidelines, 364 presentation layer, See business view preview filters in stored procedure query subjects, 254 primary keys, 78 processing SAP BW Queries troubleshooting, 253 project objects naming conventions, 19 project page, 15 Project Viewer, 15 projects, 14 adding to a repository, 50 checking in, 50 projects (cont'd) checking out, 50 copying, 45 creating, 24 creating from repositories, 50 definition, 14, 377 deleting, 46 files, 23 fixing synchronization errors, 57 Framework Manager, 23 functions, 69 linking, 44 managing, 45, 52 moving, 46 opening, 25 play back transactions, 52 publishing, 191 renaming, 46 segmenting, 43 shortcuts, 44 synchronizing, 55 verifying, 191 version control, 48 versions, 51 view transaction history, 52 Prompt Info property, 118, 170 prompts cascade on reference, 118, 170 creating, 132 creating with macros, 132 date, 118, 170 defining, 118, 170 display on reference, 119, 171 drop-down list, 118, 170 examples, 133-136 filter on reference, 119, 171 in expressions, 125, 176 mandatory, 132 optional, 132 properties, 118, 170 SAP BW variables, 177 search, 118, 170 stored procedure example, 95 text box, 118, 170 time, 118, 170 type-in, 118, 170 properties aggregation rules, 113 aggregation rules for SAP BW metadata, 166 cascade on reference, 118, 170 catalog, 67 content manager data source, 67 cubes, 67 data sources, 69 display on reference, 119, 171 filter on reference, 119, 171 function set ID, 67 modifying, 19 parameter map, 67 prompt info, 118, 170 prompt type, 118, 170 query interface, 67

User Guide 387

Index
properties (cont'd) query processing, 67 query type, 67 regular aggregate, 113, 166 rollup processing, 67 SAP BW data source, 148 SAP BW variables, 148 schema, 67 semi-aggregate, 113, 166 usage, 113, 166 viewing, 19 publishing definition, 377 metadata, 191 packages, 207 packages based on OLAP data sources, 208 projects, 191 query subjects (cont'd) converting to dimensions, 231 csv files, 205, 207 definition, 14, 378 determinants, 234 dimensions, 223 embedded files, 205, 207 exploring, 18 externalized, 205, 207 Impromptu Query Definition files, 205, 207 macros, troubleshooting, 254 properties, 19 SAP BW, 361 searching, 19 security, 200 star schema groups, 228 tab files, 205, 207 testing, 255 Transformer files, 205, 207 using in Transformer, 205 query subjects for relational metadata changing type of SQL, 102 converting, 101 converting from dimensions, 88 creating, 90, 95 data source, 89 determinants, 92 editing SQL, 102 evaluating, 100 exploring, 96 generating SQL, 106 model, 89 modifying, 91, 94, 100 parameter maps, 125 query sets, 96 relationships, 73 shortcuts, 141 SQL, 89 stored procedure, 90 testing, 98 types, 89 updating, 101 query subjects for SAP BW metadata creating, 155, 156 evaluating, 161 exploring, 156 model, 155 parameter maps, 183 query sets, 157 testing, 159 query type, 67 quotation marks, 129

Q
QE-DEF-0177, 257 queries fact-less, 228 multiple-fact, 223, 238, 241 multiple-grain, 223 single fact, 237 split, 244, 247 stitched, 213 query items converting, 85, 119 converting from measures, 84 definition, 15, 377 properties, 19 query items for relational metadata adding to query subjects, 91 aggregation rules, 116 folders, 142 modifying, 111, 119 roles, 83 usage, 116 query items for SAP BW metadata aggregation, 168 aggregation rules, 168 folders, 186 formatting, 169 modifying, 164, 171 regenerating, 169 roles, 149 usage, 167 query macros using to create prompts, 132 query processing, 67, 69 choosing, 69 query reuse, 196 query sets for relational metadata creating, 96 testing, 98 query sets for SAP BW metadata creating, 157 testing, 159 query subjects conforming, 31

R
ragged hierarchies, 82, 146, 188 recommendations segmenting and linking, 43 using network paths for file-based data sources, 66 recording transactions, 52 recursive relationships, 221 Red Brick, 323

388

Framework Manager

Index
reflexive relationships, 221 regenerating values SAP BW query items, 169 regional settings setting up a multilingual environment, 40 Regular Aggregate property, 116 relational metadata, 113 SAP BW metadata, 166, 168 regular dimensions, 212, 223 creating, 217 role-playing, 218 regular dimensions for relational metadata, 79 converting, 88 exploring, 86 hierarchies, 81 levels, 81, 82 merging, 85 scope relationships, 85 regular dimensions for SAP BW metadata, 145 exploring, 152 hierarchies, 145 levels, 145, 148 relational data source query subjects creating, 90 evaluating, 100 modifying, 94 updating, 101 relational metadata query items, 111 star schemas, 137 relationships 0-1, 74 0-n, 74 1-1, 74 1-n, 74, 215, 240 cardinality, 74 changing, 76 checking, 73, 213 creating, 77 custom, 76 definition, 73 detecting, 78 from Oracle Designer, 257 generating, 78 importing, 73 indexes and keys, 255 levels of granularity, 221 many-to-many, 74, 214 many-to-one, 74 modifying, 76 multiple valid, 218 n-n, 74 one-to-many, 74 one-to-one, 74 scope, 85, 213 shortcuts, 77, 140 verifying, 73 removing object security, 202 renaming projects, 46 relationships, 76 repairing models, 231 reporting requirements, 13 ReportNet upgrading from, 25 repositories connecting to, 48 creating, 48 creating projects based on, 50 repository control, 48 adding projects, 50 required currency not shown, 255 reserved symbols number sign, 129 reserved words, 367 resolving ambiguous objects, 244 split queries, 244, 247 restricting access, 199 BLOBs, 194 data retrieved, 194 reusing cached data, 196 reviewing models, 230 role-playing dimensions, 218 roles adding, 199 dimensions, 83 exploring, 204 roles for SAP BW metadata dimensions, 149 rollup processing, 67, 68 row limits, 194 rules aggregation for SAP BW metadata, 166 business, 120 business for SAP BW metadata, 171 cardinality, 75 rules of cardinality, 214 R-Z, 293, 295

S
sample models, 20 SAP BW, 336 importing key figures, 30 SAP BW Math, 337 SAP BW metadata, 143 importing, 30 SAP BW OLAP, 336 SAP BW Query permissions for accessing metadata, 30 SAP BW Query key figures externalizing, 362 SAP BW query subjects, 361 SAP BW Trigonometry, 336 SAP BW variables, 148, 177, 189 save as copying projects, 45 saving models troubleshooting, 253 Scale, 351 schema, 67

User Guide 389

Index
scope relationships, 78, 79, 83, 85, 145, 149, 213 script files fixing errors, 57 search for objects in the model, 47 Search pane, 47 search prompts, 118, 170 searching multiple relational dimensions, 88 multiple relational query items, 119 multiple relational query subjects, 100 multiple SAP BW dimensions, 154 multiple SAP BW query items, 171 multiple SAP BW query subjects, 161 objects, 19 Secondary Group Size (digits), 351 secured InfoCube accessing, 31 security CSVIdentityName function, 201 CSVIdentityNameList function, 201 exploring, 204 filters, 200 packages, 197 types, 199 Windows 2003 Server Edition, 255 security filters in stored procedure query subjects, 254 segmented projects, 43 copying, 45 deleting, 46 moving, 46 recommendations, 43 synchronizing, 56 segmenting projects, 43 semi-additive, 116, 168 Semi-Aggregate property, 116 relational metadata, 113 SAP BW metadata, 166, 168 session parameters creating, 128 modifying, 128, 184 setting governors, 194 settings test, 87, 99, 153, 160 shared dimensions, 222 shortcuts security, 202 shortcuts for relational metadata dimensions and query subjects, 141 relationships, 77, 140 using, 140 shortcuts for SAP BW metadata dimensions, 186 using, 185 simplifying models, 216 single fact queries, 237 single quotation marks, 129 snowflaked dimensions, 140 sort order, hierarchy, 189 sorting databases, 59 multiple relational dimensions, 88 multiple relational query items, 119 multiple relational query subjects, 100 multiple SAP BW dimensions, 154 multiple SAP BW query items, 171 multiple SAP BW query subjects, 161 sparse data and Analysis Studio, 76 split queries, 244, 247 SQL, 237 As View, 106, 107 changing type, 102 Cognos, 102, 104 comments, 102 editing, 102 generation types, 106 Minimized, 106, 107 model query subjects, 107 native, 102, 105 pass-through, 102, 105 query subjects, 89 server, connecting, 64 stand-alone native, 102, 105 SQL generation controlling, 194 SQL Server, 326 SQL Server Cast, 329 SQL Server Math, 329 SQL Server Trigonometry, 330 square brackets, 129 star dimensions, 140 star schema groups creating, 228 multiple conformed, 228 star schemas groupings, 137 multiple, 138 statistics viewing, 19 stitched queries, 213 stored procedure query subjects, 90 creating, 90 definition, 14 evaluating, 100 example, 95 Informix, 90 modifying, 94 troubleshooting, 253, 254 updating, 101 stored procedures data query updates database, 253 Summaries, 264 summaries viewing, 19 summarize aggregations relational metadata, 115 supported environments multilingual, 107, 161 supporting multiple users, 42 Sybase, 338

390

Framework Manager

Index
Sybase Math, 341 Sybase Trigonometry, 342 synchronizing fixing errors, 57 linked projects, 56 projects, 55 query subjects, 101 segmented projects, 56 troubleshooting (cont'd) query subjects, 255 query subjects with macros, 254 saving models, 253 security with Windows 2003 Server Edition, 255 stored procedure query subjects, 253, 254 stored procedures, 253 testing query subjects, 255 Windows 2003 Server Edition, 255 type-in prompts, 118, 170

T
tab files, 205, 207 tasks viewing, 19 Teradata, 331 Teradata Trigonometry, 334 testing changing settings, 87, 99, 153, 160 data source connections, 66 measure dimensions, relational, 86 measure dimensions, SAP BW, 152 projects, 191 query sets, SAP BW, 159 query sets,relational, 98 query subjects, relational, 98 query subjects, SAP BW, 159 regular dimensions, relational, 86 regular dimensions, SAP BW, 152 troubleshooting, 253, 255 text box prompts, 118, 170 text format type, 117, 169 third-party metadata, 256 Thousands Separator, 351 time limits, 194 time prompts, 118, 170 Time Separator, 351 Time Style, 351 Time Unit, 351 transaction history viewing, 52 transactions play back, 52 Transformer and query subjects, 205, 207 translation tables exporting, 109 importing, 109 translation tables for SAP BW metadata exporting, 163 importing, 163 troubleshooting Business Objects expressions, 256 calculations, 255 currency, 255 different languages, 253 ERWin stored procedures, 254 expression syntax, 253, 257 functions lists, 256 IQD, 254 macros, 254 models, 256 packages and functions lists, 256 processing SAP BW Queries, 253

U
UDA-SQL-0107, 257 UDA-SQL-0114, 257 unbalanced hierarchies, 82, 146, 188 unique identifiers, 212 objects, 19 unique keys, 231, 234 UNIX creating ODBC data sources, 64 updating model versions, 207 query subjects, 101 upgrading checklist, 25 data types, 230 FDS errors, 256 models, 25, 256 models with prompts, 258 upgrading models, 25, 230 converting, 231, 234 from ReportNet 1.x, 229 repairing, 231 reviewing, 230 warnings, 231 usage regenerating values for SAP BW metadata, 169 Usage property relational metadata, 113, 116 SAP BW metadata, 166, 167 Use Thousands Separator, 351 users adding, 199 packages, 197 using multiple data sets, 38 multiple data source connections, 59, 64 preview filters in stored procedure query subjects, 254 security filters in stored procedure query subjects, 254 using embedded strings in expressions, 129, 184 in macros, 129, 184 using literal strings in expressions, 129, 184 in macros, 129, 184 using parameters in data source query subjects, 129 using quotation marks in expressions, 129, 184 in macros, 129, 184

User Guide 391

Index

V
valid relationships multiple, 218 validating calculations, 255 relational query subjects, 100 SAP BW query subjects, 161 VARGRAPHIC datatype, 257 variables SAP BW, 177, 189 stored procedure, 95 using when externalizing, 363 vendor cannot find in functions list, 256 vendor-specific database functions, 69 troubleshooting, 257 verifying projects, 191 relationships, 73 verifying models, 191, 231 after upgrading, 256 version document, 2 versioned hierarchies, 148 versioning models, 207 projects, 51 viewing diagrams, 18 history, 51 model objects, 15 package inclusion, 204 properties, 19 statistics, 19 summaries, 19 tasks, 19 views from PowerDesigner, 257 Visual SourceSafe database creating connections, 48 Visual SourceSafe repository connections creating, 48

W
web diagrams, 138 Windows 2003 Server Edition security error messages, 255 troubleshooting, 255 With clause, 194 workflows, 213, 229

X
XML data sources connecting to, 63 XML files importing, 38

Z
Zero Value Characters, 352

392

Framework Manager