Oracle® OLAP DML Reference 10g Release 1 (10.1) Part No. B10339-02 December 2003 Oracle OLAP DML Reference, 10g Release 1 (10.1) Part No. B10339-02 Copyright © 2003 Oracle Corporation. All rights reserved. The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation. If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable: Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs. Oracle is a registered trademark, and Express, PL/SQL, and SQL*Plus are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. iii Contents Send Us Your Comments xxvii Preface xxix Intended Audience xxix Documentation Accessibility xxix Structure xxx Related Documents xxxi Conventions xxxii Part I Using the OLAP DML 1 Introduction to the OLAP DML What is the OLAP DML? 1-1 Basic Syntactical Units 1-1 OLAP DML Options 1-2 Categories of Options 1-2 Syntax for Specifying and Retrieving Option Values 1-3 OLAP DML Properties 1-3 OLAP DML Commands and Functions 1-4 OLAP DML Commands 1-4 OLAP DML Functions 1-4 OLAP DML Programs 1-5 iv OLAP DML as a Data Definition Language 1-5 Statements for Creating Analytic Workspaces 1-5 Defining Analytic Workspace Objects 1-6 Defining Data Objects Using the OLAP DML 1-7 Defining Calculation Specification Objects Using the OLAP DML 1-8 Types of Calculation Specifications 1-8 Creating Calculation Specification Objects 1-9 Viewing Data Definitions 1-10 OLAP DML as a Data Manipulation Language 1-10 Startup Programs 1-11 ONATTACH Programs 1-11 Permission Programs 1-12 AUTOGO Programs 1-12 TRIGGER_AW Program 1-12 Data Loading Programs 1-13 Programs that Copy Data From Relational Tables to Workspace Objects 1-13 File-Reading Programs 1-13 Spreadsheet Import Programs 1-14 Trigger Programs 1-14 Aggregation, Allocation, and Modeling Programs 1-15 Forecasting Programs 1-16 Programs to Export and Import Workspace Objects 1-16 2 Data Types and Operators OLAP DML Data Types 2-1 Numeric Data Types 2-2 Using LONGINTEGER Values 2-2 Using NUMBER Values 2-3 Text Data Types 2-3 Literals 2-4 Escape Sequences 2-4 Boolean Data Type 2-4 v Date Data Types 2-5 Date and Time Options 2-5 DATE Values 2-6 DATETIME Values 2-6 Calculating Dates 2-6 Converting from One Data Type to Another 2-7 OLAP DML Operators 2-7 Arithmetic Operators 2-8 Comparison and Logical Operators 2-9 Assignment Operator 2-9 3 Expressions Introducing OLAP DML Expressions 3-1 How the Data Type of an Expression is Determined 3-2 Changing the Data Type of an Expression 3-2 Using Workspace Objects in Expressions 3-3 Syntax for Specifying an Object in an Expression 3-3 Considerations When Creating and Using Qualified Object Names 3-5 When Not to Use Qualified Object Names 3-5 Using Ampersand Substitution for Workspace and Object Names 3-6 Passing Qualified Object Names to Programs 3-6 How Objects Behave in Expressions 3-6 Using Variables in Expressions 3-7 Using Variables Defined with Composites in Expressions 3-8 Dimensionality of OLAP DML Expressions 3-9 Determining the Dimensions of an Expression 3-10 How Dimension Status Affects the Results of Expressions 3-10 Changing the Dimensionality of an Expression 3-11 vi Numeric Expressions 3-11 Numeric Options 3-11 Mixing Numeric Data Types 3-12 Automatic Conversion of Numeric Data Types 3-12 Using Dimensions in Arithmetic Expressions 3-13 Using Dates in Arithmetic Expressions 3-13 Limitations of Floating Point Calculations 3-14 Controlling Errors During Calculations 3-15 Text Expressions 3-15 Working with Dates in Text Expressions 3-16 Working with NTEXT Data 3-16 Boolean Expressions 3-16 Creating Boolean Expressions 3-17 Comparing NA Values in Boolean Expressions 3-18 Controlling Errors When Comparing Numeric Data 3-19 Controlling Errors Due to Numerical Precision 3-19 Controlling Errors When Comparing Floating Point Numbers 3-20 Controlling Errors When Comparing Different Numeric Data Types 3-20 Comparing Dimension Values 3-21 Comparing Dates 3-22 Comparing Text Data 3-22 Comparing a Text Value to a Text Pattern 3-23 Comparing Text Literals to Relations 3-23 Conditional Expressions 3-24 Substitution Expressions 3-25 Working with Empty Cells in Expressions 3-26 Specifying a Value of NA 3-26 Controlling how NA values are treated 3-27 Working with the $NATRIGGER Property 3-28 Using NASKIP 3-29 Using NASKIP2 3-29 Using NAFILL 3-29 vii Working with Subsets of Data 3-30 Working with Dimension Status 3-30 Changing the Status List of a Dimension 3-31 Saving and Restoring Current Dimension Status 3-32 Specifying a List of Dimension Values for an Expression or Subexpression 3-32 Specifying a Single Data Value in an Expression 3-32 Form of a Qualified Data Reference 3-33 Qualifying a Variable 3-33 Replacing a Dimension in a Variable 3-34 Qualifying a Relation 3-35 Qualifying a Dimension 3-36 Using Ampersand Substitution with QDRs 3-36 Using the QUAL Function to Specify a QDR 3-37 4 Formulas, Aggregations, Allocations, and Models Formulas 4-1 Aggregations 4-2 Aggregating Data 4-3 Executing the Aggregation 4-4 Creating Custom Aggregates 4-6 Allocations 4-7 Allocating Data 4-8 Handling NA Values 4-9 Models 4-10 Creating Models 4-10 Nesting Models 4-11 Dimension Status and Model Equations 4-12 Using Data from Past and Future Time Periods 4-12 Handling NA Values 4-13 Solving Simultaneous Equations 4-13 Modeling for Multiple Scenarios 4-14 Compiling a Model 4-14 Understanding Dependencies 4-15 Checking for Additional Problems 4-15 viii Running a Model 4-15 Dimensions of Solution Variables 4-16 Solution Variables Dimensioned by a Composite 4-17 Debugging a Model 4-18 5 OLAP DML Programs Creating OLAP DML Programs 5-1 Specifying Program Contents 5-2 Creating User-Defined Functions 5-2 Passing Arguments 5-3 Using Multiple Arguments 5-3 Handling Arguments Without Converting Values to a Specific Data Type 5-4 Passing Arguments as Text with Ampersand Substitution 5-4 Program Flow-of-Control 5-5 Looping Nature of OLAP DML Commands and Functions 5-5 Flow-of Control Commands 5-6 Preserving the Environment Settings 5-8 Changing the Program Environment 5-8 Ways to Save and Restore Environments 5-9 Saving the Status of a Dimension or the Value of an Option 5-9 Saving Several Values at Once 5-10 Using Level Markers 5-10 Using CONTEXT to Save Several Values at Once 5-10 Handling Errors 5-10 Trapping an Error 5-11 Suppressing Error Messages 5-11 Creating Your Own Error Messages 5-12 Handling Errors in Nested Programs 5-12 Handling Errors While Saving the Session Environment 5-13 Compiling Programs 5-13 Finding Out If a Program Has Been Compiled 5-14 Programming Methods That Prevent Compilation 5-14 ix Testing and Debugging Programs 5-14 Error and Debugging Options 5-15 Generating Diagnostic Messages 5-16 Identifying Bad Lines of Code 5-16 Sending Output to a Debugging File 5-16 Executing Programs 5-17 Part II Alphabetic Reference 6 $AGGMAP to AGGMAP $AGGMAP 6-3 $AGGREGATE_FROM 6-5 $AGGREGATE_FROMVAR 6-7 $ALLOCMAP 6-9 $COUNTVAR 6-11 $NATRIGGER 6-13 $STORETRIGGERVAL 6-18 $VARCACHE 6-20 ABS 6-25 ACQUIRE 6-27 ACROSS 6-33 ADD_MONTHS 6-35 AGGMAP 6-37 AGGINDEX 6-63 BREAKOUT DIMENSION 6-67 CACHE 6-70 DIMENSION (for aggregation) 6-74 DROP DIMENSION 6-75 MEASUREDIM (for aggregation) 6-78 MODEL (in an aggregation) 6-80 RELATION (for aggregation) 6-82 AGGMAP ADD or REMOVE model 6-98 AGGMAP SET 6-101 x 7 AFFMAPINFO to ARCCOS AGGMAPINFO 7-3 AGGREGATE command 7-9 AGGREGATE function 7-23 AGGREGATION 7-33 ALLCOMPILE 7-35 ALLOCATE 7-36 ALLOCERRLOGFORMAT 7-46 ALLOCERRLOGHEADER 7-48 ALLOCMAP 7-50 CHILDLOCK 7-56 DEADLOCK 7-57 DIMENSION (for allocation) 7-58 ERRORLOG 7-59 ERRORMASK 7-60 MEASUREDIM (for allocation) 7-61 RELATION (for allocation) 7-62 SOURCEVAL 7-70 VALUESET 7-71 ALLSTAT 7-76 ANTILOG 7-77 ANTILOG10 7-78 ANY 7-79 ARCCOS 7-83 8 ARCSIN to CHARLIST ARCSIN 8-3 ARCTAN 8-4 ARCTAN2 8-5 ARG 8-6 ARGCOUNT 8-10 ARGFR 8-12 ARGS 8-16 ARGUMENT 8-19 ASCII 8-26 [...]... using Oracle OLAP in the Enterprise Edition of Oracle Database ■ Oracle OLAP Reference Explains the syntax of PL/SQL packages and types and the column structure of views related to Oracle OLAP xxxi ■ Oracle OLAP Java API Reference Introduces the Oracle OLAP API, a Java application programming interface for Oracle OLAP, which is used to perform online analytical processing of the data stored in an Oracle. .. to the OLAP DML This chapter provides an introduction to the OLAP DML It includes the following topics: ■ What is the OLAP DML? ■ Basic Syntactical Units ■ OLAP DML as a Data Definition Language ■ OLAP DML as a Data Manipulation Language What is the OLAP DML? The OLAP DML is a language that defines and manipulates data in an analytic workspace ■ ■ As a data definition language, you can use DML statements... about OLAP DML statements Appendix A, "Functions and Commands by Functional Category" This appendix lists the OLAP DML functions, commands, and programs by functional category Appendix B, "OLAP DML Statement Changes" This appendix provides information about recent changes to the OLAP DML Related Documents The following documents provide additional information about using Oracle OLAP: ■ Oracle OLAP Application... Structure This document is structured in the following three parts Part I, "Using the OLAP DML" Introduces the basic concepts of analyzing data using the OLAP DML Chapter 1, "Introduction to the OLAP DML" Provides an introduction to the OLAP DML and provides some basic information that you need to know to effectively use the OLAP DML Chapter 2, "Data Types and Operators" Introduces the OLAP DML data types... the software, please contact your local Oracle Support Services xxvii xxviii Preface The Oracle OLAP DML Reference provides a complete description of the OLAP Data Manipulation Language (OLAP DML) used to define and manipulate analytic workspace objects Part I briefly describes how to use the OLAP DML Part II consists of a reference topic for each of the OLAP DML statements Intended Audience This manual... "Expressions" Explains how to create and use OLAP DML expressions Chapter 4, "Formulas, Aggregations, Allocations, and Models" Explains how to create and execute OLAP DML calculation specification objects Chapter 5, "OLAP DML Programs" Explains how to create, test, and execute OLAP DML programs Part II, "Alphabetic Reference" Consists of a topic for each of the OLAP DML statements, arranged alphabetically... the OLAP DML Part I introduces the basic concepts of the OLAP DML and contains overview information about using the OLAP DML to perform multidimensional analysis This part contains the following chapters: ■ Chapter 1, "Introduction to the OLAP DML" ■ Chapter 2, "Data Types and Operators" ■ Chapter 3, "Expressions" ■ Chapter 4, "Formulas, Aggregations, Allocations, and Models" ■ Chapter 5, "OLAP DML. .. the API and how to discover metadata, create queries, and retrieve data ■ Oracle OLAP Java API Reference Describes the classes and methods in the Oracle OLAP Java API for querying analytic workspaces and relational data warehouses ■ Oracle OLAP Analytic Workspace Java API Reference Describes the classes and methods in the Oracle OLAP Java API for building and maintaining analytic workspaces Conventions... of how Oracle OLAP calculates or formats data or what Oracle OLAP operations are activated You cannot define an option as part of a workspace However, you can use any of the options that are defined as part of the Oracle OLAP DML Some options are read-only, while others are read/write options for which you can specify values Read/write options have default values Categories of Options OLAP DML options... analysis and reporting OLAP DML commands, functions, options, programs, and properties are collectively referred to as OLAP DML statements Part I of this manual introduces basic elements of the OLAP DML The complete syntax of each statement, usage notes, and examples is provided in Part II of this manual Lists of statements, arranged by functional category are presented in Appendix A OLAP DML Options An option . 1-3 OLAP DML Properties 1-3 OLAP DML Commands and Functions 1-4 OLAP DML Commands 1-4 OLAP DML Functions 1-4 OLAP DML Programs 1-5 iv OLAP DML as a Data Definition. Oracle OLAP DML Reference 10g Release 1 (10.1) Part No. B10339-02 December 2003 Oracle OLAP DML Reference, 10g Release 1 (10.1)