Metacube SDK for Snap-Ins Programmer's Manual

SDK for Snap-Ins Programmer’s Manual

MetaCubeTM ROLAP Option for Informix® Dynamic ServerTM

Version 4.0 January 1998 Part No. 000-4194  Published by INFORMIX Press Informix Software, Inc. 4100 Bohannon Drive Menlo Park, CA 94025-1032  Copyright 1981-1998 by Informix Software, Inc. or its subsidiaries, provided that portions may be copyrighted by third parties, as set forth in documentation. All rights reserved.

The following are worldwide trademarks of Informix Software, Inc., or its subsidiaries, registered in the  United States of America as indicated by “ ,” and in numerous other countries worldwide:         Answers OnLine ; INFORMIX ; Informix ; Illustra ; C-ISAM ; DataBlade ; Dynamic Server ; Gateway ;   NewEra ; MetaCube

All other names or marks may be registered trademarks or trademarks of their respective owners.

RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS Software and documentation acquired with US Government funds are provided with rights as follows: (1) if for civilian agency use, with Restricted Rights as deﬁned in FAR 52.227-19; (2) if for Dept. of Defense use, with rights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribed in DFAR 227.7202. Any whole or partial reproduction of software or documentation marked with this legend must reproduce the legend.

ii SDK for Snap-Ins Programmer’s Manual Table of Contents Table of Contents

Introduction About This Manual ...... 3 Organization of this Manual ...... 3 Types of User ...... 4 Documentation ...... 4 Printed Documentation ...... 4 Online Help ...... 6 Readme Files ...... 7 Related Reading ...... 7 Compliance with Industry Standards ...... 8 Informix Welcomes Your Comments ...... 8

Chapter 1 Basic Concepts MetaCube’s C++ and OLE Interfaces ...... 1-3 Object Hierarchies ...... 1-4 Collections ...... 1-5 Parents and Children...... 1-5 Inheritance ...... 1-8 Object Naming Restrictions ...... 1-9 ValueList Objects ...... 1-9 Standard Data Types ...... 1-10 Frequently Referenced Header Files ...... 1-10 error.h...... 1-10 metacons.h ...... 1-10 sdk.h ...... 1-11 Using the Get_m_ Functions ...... 1-15

Chapter 2 Using the SDK Extension Wizard Sample Snap-In Extension ...... 2-3 Generating a Template .cpp File ...... 2-4 Editing Sample Code in the .cpp File ...... 2-5 Changing the Description of the Extension’s Arguments . . . 2-6 Changing the Extension’s Argument Types...... 2-7 Validating the Type and Value of All Arguments ...... 2-9 Creating the Process Code ...... 2-12 Creating Multiple Extensions in a Snap-In ...... 2-17 Building and Testing an Extension ...... 2-19 Sample Extension’s Code ...... 2-21

Chapter 3 MetaCube Class Library Reference CDb...... 3-3 CDimKey ...... 3-15 CIExtension ...... 3-24 CMetaObject ...... 3-29 COlapException ...... 3-34 COlapObject ...... 3-36 COleCollection ...... 3-41 CParseNode ...... 3-53 CPlugIn ...... 3-58 CQueryCube ...... 3-60 CSelect ...... 3-85 Extension ...... 3-88 Extensions ...... 3-98 Filter ...... 3-101 FilterElement ...... 3-109 FilterElements ...... 3-115 Filters ...... 3-120 Folder ...... 3-126 Folders ...... 3-133 Metabase ...... 3-136 MetaCube ...... 3-172 MetaCubes ...... 3-202 Queries ...... 3-205 Query ...... 3-207 QueryBackJob ...... 3-234 QueryBackJobs ...... 3-245 QueryCategories ...... 3-248 QueryCategory ...... 3-253 QueryItem ...... 3-264 QueryItems ...... 3-275 Summaries ...... 3-280 iv SDK for Snap-Ins Programmer’s Manual Summary ...... 3-286 ValueList ...... 3-291

Index

Table of Contents v vi SDK for Snap-Ins Programmer’s Manual Introduction Introduction

About This Manual...... 3 Organization of this Manual ...... 3 Types of User ...... 4 Documentation ...... 5 Printed Documentation ...... 5 Typeface ...... 6 Online Help ...... 7 Readme Files ...... 7 Related Reading ...... 8 Compliance with Industry Standards ...... 8 Informix Welcomes Your Comments ...... 9 2 SDK for Snap-Ins Programmer’s Manual his manual explains how to use the MetaCube C++ Application TProgramming Interface (API) and MetaCube’s SDK Extension Wizard to create custom Snap-In extensions to the analytical capabilities of MetaCube Explorer and MetaCube for Excel.

About This Manual

The MetaCube SDK for Snap-Ins Programmer’s Manual contains information to assist you in developing extensions to the capabilities of the MetaCube analysis engine, such as a set of ﬁnancial and analytical formulas that meet the particular requirements of your organization. The SDK Extension Wizard can generate code for a template Snap-In, which you can modify to meet your needs. After compiling and testing this code, your new extension can be easily inserted, or “snapped into” MetaCube Explorer or MetaCube for Excel. This manual explains some of the general concepts a programmer should understand when developing custom extensions to the MetaCube analysis engine, it explains how to use the SDK Extension Wizard, and it provides a full description of the class library that constitutes MetaCube’s C++ API.

Organization of this Manual

The chapters in this manual describe how to use MetaCube’s API and the SDK Extension Wizard to quickly create custom extensions. The manual includes the following chapters.

■ This Introduction provides an overview of the manual ■ Chapter 1, “Basic Concepts,”explains some of the general principles you should understand before writing your own custom extensions. First-time users should read this chapter to be sure you understand all the features of MetaCube’s C++ API.

Introduction 3 Types of User

■ Chapter 2, “Using the SDK Extension Wizard,”explains the procedure necessary to use a wizard to generate template code for an extension. It also describes how to modify that code so it can perform the calculations and changes required for your new extension. Finally it explains how to test the new extension and how to snap it into MetaCube Explorer. ■ Chapter 3, “MetaCube Class Library,”details the entire contents of MetaCube’s C++ API. It describes every MetaCube class accessible through the SDK, and describes every member function and data member within each class.

Types of User

This manual is written for programmers who are developing custom extensions for MetaCube Explorer or MetaCube for Excel. You should be experienced with Microsoft Visual C++, Microsoft Foundation Class (MFC) Libraries, Object Linking and Embedding (OLE) and the Microsoft Developer Studio. You should also be familiar with MetaCube Explorer.

4 SDK for Snap-Ins Programmer’s Manual Documentation

Documentation

MetaCube product documentation contains two key components:

■ printed documentation ■ online help

Printed Documentation

The printed documentation for MetaCube products is divided into two distinct types:

■ manuals for products with graphical user interfaces ■ manuals for application development tools Manuals for products with user interfaces contain information about the various features of the product. This information is fairly high-level and conceptual in nature. These manuals are designed to give you information about the purpose of the product and what its capabilities are. Manuals for application development tools are reference manuals that provide technical information about the tools. In addition to this book, printed manuals for other MetaCube products include the following:

■ MetaCube Explorer User’s Guide. This manual is written for people who are responsible for analyzing data about their company’s business. It describes the features of MetaCube Explorer for querying a MetaCube data warehouse in multi-dimensional terms to obtain meaningful reports that are the basis for timely business decisions. ■ MetaCube for Excel User’s Guide. This manual is written for people who use Microsoft’s Excel spreadsheet for business analysis. After adding in MetaCube for Excel to the Excel software, an Excel user can query a MetaCube data warehouse in multi-dimensional terms to obtain spreadsheet or PivotTable reports.

Introduction 5 Printed Documentation

■ MetaCube Warehouse Manager’s Guide. This manual is written for the data warehouse administrator and describes how to specify internal information about the data warehouse so that the MetaCube components are able to access and graphically present the database for querying. ■ MetaCube Data Warehouse Administrator’s Guide. This guide is written for the data warehouse administrator. It describes the overall process of developing a data warehouse and it introduces the tools for managing a data warehouse—MetaCube Secure Warehouse, MetaCube Agent Administrator, and MetaCube Warehouse Optimizer. ■ MetaCube Application Programmer’s Manual. This manual is written for a programmer who will write custom applications that interact with the MetaCube analysis engine. This manual describes MetaCube’s OLE Automation programming interface. ■ MetaCube SQL Optimizer User’s Guide. This manual describes how to use the MetaCube SQL Optimizer for connecting third-party query tools or custom query applications to the MetaCube analysis engine to access a MetaCube data warehouse. Queries are optimized to run against aggregate and sample tables, thereby significantly improving query performance against very large data warehouses. ■ MetaCube Installation and Configuration Guide. This manual describes how to install and configure the MetaCube software components on both the server and on PCs.

Typeface

The text in this manual uses the following set of conventions.

Convention Meaning

italics Emphasized words appear in italics. Also used for the names of MetaCube components and some terms that are speciﬁc to MetaCube Web Explorer

boldface Used for the names of menu options, popup menu options, and dialog boxes.

monospace Used for information that the product displays and information that you type.

6 SDK for Snap-Ins Programmer’s Manual Online Help

Online Help

Each MetaCube product that employs a graphical user interface includes an extensive online help system that provides step-by-step instructions on the use of the product. The help system for most MetaCube products is accessed from the Help menu and consists of the following components:

■ Help Topics: displays a complete online help system that contains “how to” topics and procedural information on using the product. ■ Context Sensitive Help: allows the user to access help specifically on a feature of the user interface. Selecting this menu option changes the cursor into a help cursor. Clicking a feature of the window with the help cursor displays help about that specific feature. ■ Help on Help: contains instructions on using the MetaCube online help. For the user unfamiliar with online help, this help system explains how to use the various features of MetaCube’s online help system. Context-sensitive help can be accessed by clicking the Help button on an application’s toolbar in the main window. After clicking the Help button, clicking any feature of the window provides help about that specific feature. Clicking the Help button is the same as clicking Context Sensitive Help on the window’s Help menu. In dialog boxes, pressing F1 displays a help topic that describes the features of that dialog box. From that topic, the user may jump to the main help system or, in many cases, to a procedural help topic that describes how to use the dialog box. In the main window of an application, after activating an area of the window by clicking it, F1 provides a help topic that describes that particular area of the window.

Readme Files

In addition to the printed manuals, readme files are distributed with MetaCube products. These files contain technical information, including last- minute changes to product capability or documentation. Please read these files, as they contain important information.

Introduction 7 Related Reading

Related Reading

For more information about Informix SQL, refer to the following Informix manuals:

■ Informix Guide to SQL: Syntax ■ Informix Guide to SQL: Reference ■ Informix Guide to SQL: Tutorial

For information on data warehousing, see The Data Warehouse Toolkit, by Ralph Kimball (John Wiley & Sons, Inc., 1996).

Compliance with Industry Standards

The American National Standards Institute (ANSI) has established a set of industry standards for SQL. Informix SQL-based products are fully compliant with SQL-92 Entry Level (published as ANSI X3.135-1992), which is identical to ISO 9075:1992, on Informix Dynamic Server. In addition, many features comply with the SQL-92 Intermediate and Full Level and X/Open C CAE (common applications environment) standards.

Informix SQL-based products are compliant with ANSI SQL-92 Entry Level (published as ANSI X3.135-1992) with the following exceptions:

■ Effective checking of constraints. ■ Serializable transactions.

8 SDK for Snap-Ins Programmer’s Manual Informix Welcomes Your Comments

Informix Welcomes Your Comments

Please tell us about our documentation. To help us with future versions of our manuals and online help, we want to know about any corrections or clariﬁ- cations that you would ﬁnd useful. Please include the following information:

■ The name and version of the manual that you are using ■ Any comments that you have about the manual ■ Your name, address, and phone number Write to us at the following address: Informix Software, Inc. Technical Publications 300 Lakeside Drive, Suite 2700 Oakland, CA 94612 If you prefer to send electronic mail, our address is: [email protected] Or, send a facsimile to Technical Publications at: 650-926-6571 We appreciate your feedback.

Introduction 9 Informix Welcomes Your Comments

10 SDK for Snap-Ins Programmer’s Manual Chapter Basic Concepts 1

MetaCube’s C++ and OLE Interfaces...... 1-3 Object Hierarchies ...... 1-4 Collections ...... 1-5 Parents and Children ...... 1-5 Inheritance ...... 1-8 Object Naming Restrictions ...... 1-9 ValueList Objects ...... 1-9 Standard Data Types ...... 1-10 Frequently Referenced Header Files ...... 1-10 error.h...... 1-10 metacons.h ...... 1-11 sdk.h ...... 1-12 Macros ...... 1-12 Buffer Sizes ...... 1-14 Types ...... 1-15 Using the Get_m_ Functions ...... 1-16 1-2 SDK for Snap-Ins Programmer’s Manual his chapter discusses some basic concepts you should understand Tbefore using the MetaCube C++ programming interface to create your own custom extensions to the MetaCube analysis engine. It explains the relationship between MetaCube’s C++ and OLE programming interfaces, describes the nature of MetaCube’s class hierarchy, details aspects of the application programming interface (API) that are commonly referenced, and discusses a C++ programming technique that may be unfamiliar to some users.

MetaCube’s C++ and OLE Interfaces

MetaCube consists of a library of object classes created in C++. To develop custom applications, such as modiﬁed versions of Explorer or MetaCube for Excel, MetaCube offers an OLE programming interface. With it, you can issue messages in the form of OLE automation calls to MetaCube’s class library. MetaCube’s OLE programming interface is fully documented in the MetaCube Application Programmer’s Manual. You can also develop custom extensions to the MetaCube engine itself. For example, you may want to create larger sets of statistical or ﬁnancial formulas to analyze data. To make custom extensions, use MetaCube’s SDK Extension Wizard and its C++ Application Programming Interface (API). This document, the MetaCube SDK for Snap-Ins Programmer’s Manual, explains how to create custom extensions.

Basic Concepts 1-3 Object Hierarchies

Although many MetaCube classes support OLE automation calls, some classes apply exclusively to the internal functionality of the MetaCube analysis engine. The names of all MetaCube classes that do not support OLE automation begin with the letter C. Those classes are: CDb CDimKey CIExtension CMetaObject COlapException COleCollection CParseNode CPlugIn CQueryCube CSelect Some MetaCube classes, such as FactTable, Aggregate, and Dimension, are used exclusively for deﬁning metadata rather than the analytic processes that act on metadata. This manual does not describe these classes and the OLE automation calls used to manipulate them, although Figure 2 on page 1-7 does show the metadata classes and their relationship to the overall MetaCube hierarchy. For information on the metadata object classes, see the MetaCube Application Programmer’s Manual.

Object Hierarchies

To understand all of the relationships between the MetaCube classes, you should be familiar with the following principles as they relate to the MetaCube C++ programming interface:

■ collections ■ parent/child relationships ■ inheritance

1-4 SDK for Snap-Ins Programmer’s Manual Collections

Collections

In MetaCube, objects of the same class are assembled into groups of objects, known as collections. Each collection of objects belongs to another object, called a parent. The name of a collections-class object is the plural of an object held in that collection. For example, an object of the Queries class (note the plural name) holds a collection of Query objects (note the singular name). In general, a collection of objects defines some aspect of the collection’s parent object. For example a Query object is the parent of a QueryItems collection, and the QueryItem objects in that collection partially define the query. Some types of objects, particularly Query and Metabase objects, contain multiple collections. A Query object, for example, contains collections of MetaCube, QueryItem, QueryCategory, and Filter objects. Together those collections define the query represented by the Query object. Figure 1 on page 1-6 shows the hierarchical relationships between parent objects and the collections that are their children. In that figure, note that most instances of a singular object are contained within a collection of like objects. For example, the QueryItems collection contains a QueryItem object; a Filters collection contains a Filter object.

Parents and Children

Most externally accessible MetaCube objects are arranged hierarchically. An object of the Metabase class is the master object in the hierarchy. Most of the other MetaCube objects are children, grandchildren, or great-grandchildren of that Metabase object. Figure 1 on page 1-6 shows the hierarchical relationships between the MetaCube classes accessible through the SDK programming interface. For your reference, Figure 2 on page 1-7 shows all other MetaCube classes not directly accessible through the SDK programming interface. Note that Figure 1 and Figure 2 do not illustrate inheritance relationships between classes. Except for CQueryCube, none of the internal classes of objects (those whose names begin with “C”) are members of the MetaCube hierarchy of object classes. The internal classes provide particular types of functionality, or they function as abstract base classes, described in “Inheritance” on page 1-8.

Basic Concepts 1-5 Parents and Children

Figure 1 MetaCube Class Hierarchy Exposed Through API

Metabase

RootFolder Queries QueryBackJobs Extensions additional Query QueryBackJob Extension folders Folders Folder

Filters MetaCubes QueryCategories QueryItems Filter MetaCube QueryCategory QueryItem CQueryCube

FilterElements Summaries FilterElement Summary

to any object derived from COlapObject

ValueList

1-6 SDK for Snap-Ins Programmer’s Manual Parents and Children

Figure 2 MetaCube Class Hierarchy Not Exposed Through API

to Metabase Object

Dimensions FactTables DSSSystems Dimension FactTable DSSSystem

SystemMessages Schemas Users SystemMessage Schema User

DimensionElements Tables Available DSSSystems DimensionElements Table DSSSystem

Attributes Columns Attribute Column

Samples Measures Aggregates DimensionMappings Sample Measure Aggregate DimensionMapping

SampleQualiﬁers AggregateGrants AggregateMeasures

to Query Object SampleQualiﬁer AggregateGrant AggregateMeasure

DrillDataSources AggregateGroups AggregateIndexes FactTable AggregateGroup AggregateIndex

Basic Concepts 1-7 Inheritance

Inheritance

All MetaCube classes of objects are derived from existing classes of objects— either other MetaCube objects or objects in the Microsoft Foundation Class Library. A derived class inherits the description of another class, known as a base class, but the derived class includes additional member variables and functions. Three classes of MetaCube objects—COlapObject, CMetaObject, and COleCollection—function as abstract base classes. These are classes that cannot be instantiated but are used as a base class from which other classes are derived. For example, all MetaCube objects accessible through the SDK programming interface are derived from the COlapObject class. All MetaCube collection classes are derived from the COleCollection class, which, in turn, is derived from COlapObject. Figure 3 shows the hierarchy chart for a Queries object. It is derived from COleCollection, which in turn is derived from COlapObject. All COlapObjects are derived from CCmdTarget and CObject. CCmdTarget is the base class for the Microsoft Foundation Class Library message-map architecture. CObject is the principal base class for the entire Microsoft Foundation Class Library. Figure 3 CObject Hierarchy Chart for the Queries Class CCmdTarget

COlapObject

COleCollection

Queries

Chapter 3, “MetaCube Class Library,” describes all of the MetaCube classes, and it provides a hierarchy chart for each class. This chart is particularly useful for determining an object’s base class. For information on the functions that a particular class inherits, refer to the other classes depicted in the hierarchy chart.

1-8 SDK for Snap-Ins Programmer’s Manual Object Naming Restrictions

Object Naming Restrictions

MetaCube imposes certain restrictions when deﬁning an object name. The string used for an object name:

■ cannot be empty ■ cannot begin with a space ■ must contain at least one non-numeric character ■ cannot contain any of the following characters:

Character Description

, comma

. period

" quotation mark

\t tab

\n new line

( left parenthesis

) right parenthesis

[ left bracket

] right bracket

' single quote

ValueList Objects

ValueList objects are used to store sets of values created by some other MetaCube class. Many member functions in the MetaCube class library return ValueList objects or IDispatch pointers (OLE handles, that is) to ValueList objects. Items in a ValueList object can be stored as an array or a tab-delimited string.

Basic Concepts 1-9 Standard Data Types

Standard Data Types

To ensure that the data types used in the MetaCube class library have standard lengths, the SDK programming interface employs only four types:

■ long (4 bytes) ■ double (8 bytes) ■ string (null-terminated) ■ Boolean

Frequently Referenced Header Files

Throughout the SDK’s programming interface, three header ﬁles are frequently referenced:

■ error.h ■ metacons.h ■ sdk.h

error.h

The error.h file lists #define directives that assign a name and a code for all OLAP error messages. For an error that causes a COlapException object to be thrown, the member function COlapException::Get_m_code() returns a reference to the appropriate code, as defined in error.h.

1-10 SDK for Snap-Ins Programmer’s Manual metacons.h metacons.h

The metacons.h file defines external constants used by various member functions throughout the SDK programming interface. At the appropriate locations throughout Chapter 3, “MetaCube Class Library,” constants are listed and defined. The metacons.h file defines the following types of constants:

■ General ■ Format strings ■ Dimension types ■ Filter types ■ QueryItem calculations ■ MetaCube cell types ■ Sort directions ■ Orientations ■ Summary ■ Database vendor types ■ Informix database constants ■ Olap server client types ■ Database connect methods ■ Job recurrency types ■ Job status values ■ Attribute/Measure display styles ■ Column data types ■ Veriﬁcation results ■ Format codes

Basic Concepts 1-11 sdk.h

sdk.h

The sdk.h file serves as the entry point for the header files generated by the SDK Extension Wizard. These header files contain all the class declarations for the MetaCube class library as well as the error.h and metacons.h files (described in the previous sections) and resource.h, a file generated by Microsoft Visual C++. The sdk.h file also defines macros, buffers, and data types that may be useful when using the SDK programming interface. They are described in the following sections.

Macros

The sdk.h ﬁle deﬁnes the following macros that may be useful programming tools when using the MetaCube class library:

■ IsA() ■ DispIsA() ■ MAKENULLS() ■ genclr() ■ NULLP() ■ NULLV()

IsA()

Determines whether an object pointer points to a member of a particular class and returns TRUE or FALSE.

IsA(objptr, type) Parameters

objptr An object pointer

type The class being compared to the object pointer

1-12 SDK for Snap-Ins Programmer’s Manual sdk.h

DispIsA()

Determines whether an IDispatch pointer points to a member of a particular class and returns TRUE or FALSE.

DispIsA(disp, type) Parameters disp An IDispatch pointer type The class being compared to the IDispatch pointer

MAKENULLS()

Makes an array of null values. This macro is particularly useful when calling CDb::ExecuteStmt(), which includes an optional argument that provides an array of nulls.

MAKENULLS(var1, var2, count) Parameters var1 The location where nulls to be placed into the array are currently stored var2 The array where the nulls will be placed. This value is passed in as a parameter to a function such as CDb::ExecuteStmt(). count The number of items in the array genclr()

Clears a speciﬁed amount of memory from a designated location.

genclr(ptr, sz) Parameters ptr The location of the memory to be cleared sz The amount of memory to be cleared

Basic Concepts 1-13 sdk.h

NULLP()

Makes a null pointer to a speciﬁed data type.

NULLP(type) Parameters

type The data type to which a null pointer is being made

NULLV()

Makes a null value of a speciﬁed data type.

NULLV(type) Parameters

type The data type of which a null value is being made

Buffer Sizes

The sdk.h deﬁnes four standard buffer sizes:

#define TN_BUF 31 #define SM_BUF 81 #define MD_BUF 241 #define LG_BUF 1025

1-14 SDK for Snap-Ins Programmer’s Manual sdk.h

Types

The sdk.h deﬁnes three templated array types:

■ CLongArray—an array of long integers, defined with the following statement: typedef CArray CLongArray; ■ CDoubleArray—an array of doubles, defined with the following statement: typedef CArray CDoubleArray; ■ CKeyArray—an array of CDimKey objects, defined with the following statement: typedef CArray CKeyArray; The sdk.h includes a struct data type called SCell, which defines the value of each cell in the QueryCube generated by processing a query. The SCell struct appears as follows:

typedef struct cell { double cell_value; CString cell_format; long cell_item_index; double cell_error } SCell; The members of the SCell structure are listed and deﬁned below: cell_value A double containing the value of the cell cell_format A CString containing the syntax used for formatting numeric data in different display environments. Typically cell formatting is supplied by the MetaCube Warehouse Manager, but QueryItem::SetFormatString() can be used to control the format of cells for a particular QueryItem. cell_item_index An index into the QueryItem collection associated with this query cell_error A double containing the error value for a cell, if sampling is used for this query

Basic Concepts 1-15 Using the Get_m_ Functions

Using the Get_m_ Functions

Throughout the SDK programming interface, many object classes include member functions that begin with “Get_m_”, such as Query::Get_m_author() or Filter::Get_m_group(). All of the Get_m_ functions return references. You can change the value to which a returned reference points. The Get_m_ functions provide an alternative approach to pairs of “get” and “set” member functions. A Get_m_ function can retrieve a reference, similar to a “get” member function, but the reference returned by a Get_m_ function can be changed, accomplishing the same effect as calling a “set” function. Some MetaCube object classes include Get_m_ member functions that accomplish essentially the same thing as related pairs of “get” and “set” member functions. Typically, the “get” and “set” functions return OLE handles to objects or data types while the Get_m_ functions reference C++ objects. For example, in the QueryCategory class, you can call GetName() to retrieve an OLE string containing the name of the QueryCategory object. You can call SetName() to change the name of the QueryCategory object contained in that OLE string. Similarly, you can call Get_m_name() to retrieve a CString containing the name of the QueryCategory object. To change the name of the QueryCategory object, you can change the value of the CString referenced by Get_m_name().

1-16 SDK for Snap-Ins Programmer’s Manual Chapter Using the SDK Extension Wizard 2

Sample Snap-In Extension ...... 2-3 Generating a Template .cpp File ...... 2-4 Editing Sample Code in the .cpp File...... 2-6 Changing the Description of the Extension’s Arguments .... 2-6 Changing the Extension’s Argument Types ...... 2-8 Validating the Type and Value of All Arguments ...... 2-9 Understanding the Validate Function ...... 2-11 Creating the Process Code ...... 2-12 Understanding the Process Function ...... 2-12 Creating Multiple Extensions in a Snap-In ...... 2-17 Generating Headers for Multiple Extensions ...... 2-18 Generating Functions for Multiple Extensions ...... 2-19 Building and Testing an Extension ...... 2-19 Sample Extension’s Code...... 2-21 2-2 SDK for Snap-Ins Programmer’s Manual his chapter describes how to use the SDK Extension Wizard to create Ta .cpp file that contains template code for a MetaCube snap-in extension. It explains how to modify that template code to create your own customized snap-in extension or extensions. This chapter also describes how to build and test a MetaCube Snap-In. The procedures in this chapter describe the minimum changes necessary to customize a .cpp file so that it can successfully snap in to MetaCube Explorer or MetaCube for Excel. When creating your own Snap-Ins, use the MetaCube API to modify a .cpp file in any way that best suits your needs.

Sample Snap-In Extension

Throughout this chapter, a single example illustrates the process of using the SDK Extension Wizard. This sample extension calculates a harmonic moving average, which takes n number of values, multiplies those values together, and then derives the nth root of that number. Harmonic moving averages are useful for deriving averages that discount the value of a few outlying data points. The sample Snap-In is created in a Microsoft Developer Studio project called “harmonics.” The .cpp file generated for this example is named harmonics.cpp. “Sample Extension’s Code” on page 2-21 shows the entire harmonics.cpp file after all modifications are complete.

Using the SDK Extension Wizard 2-3 Generating a Template .cpp File

Generating a Template .cpp File

This section describes how to use the SDK Extension Wizard to generate a template .cpp ﬁle. The code that the Wizard automatically generates is a functional extension that doubles the value of a measure. You must edit this code to implement the functionality you want for your own snap-in extensions. Although the SDK Extension Wizard generates a template ﬁle that contains a single extension, a Snap-In can contain multiple extensions. “Creating Multiple Extensions in a Snap-In” on page 17 describes the procedures necessary to create multiple extensions within a single Snap-In. To access the SDK Extension Wizard:

1. Open Microsoft Developer Studio. 2. On the File menu click New. 3. From the New Dialog box, click Project Workspace and then click OK. 4. Complete the Project Workspace dialog box by doing the following: a. In the Type list, click Meta3 Extension Wizard. b. In the Name box, type a name for the new workspace. For the sample extension, the workspace is named “harmonics.” c. If necessary, type new information in the Platforms and Location boxes. d. Click Create. Step 1 of the SDK Extension Wizard is displayed. To perform the SDK Extension Wizard Step 1:

The dialog box associated with Step 1 provides introductory material. After reading it, click Next. The dialog box associated with Step 2 of the SDK Extension Wizard is displayed.

2-4 SDK for Snap-Ins Programmer’s Manual Generating a Template .cpp File

To perform the SDK Extension Wizard Step 2:

1. In the Extension Name box, type a name for the extension you are creating. The sample extension is named “HarmonicMovingAvg.” The name you enter here will be used in the code that the SDK Extension Wizard automatically generates for the extension. MetaCube Explorer also uses this text string to identify an extension. Consequently, you may want to choose a name that is descriptive. The name cannot include spaces, but it can include upper and lower case letters and underscores. Names longer than 25 characters may be truncated when they are displayed in Explorer. 2. In the Extension Description box, type a description for the extension. Explorer and MetaCube for Excel present this text as a description of the extension. For the sample extension, the description is “Harmonic moving average.” 3. In the Number of Arguments box, type in the number of arguments needed for the extension or click the arrows to specify a number. The ﬁrst argument identiﬁes the measure on which the extension operates, so all extensions require at least one argument. For the sample extension, two arguments are necessary. 4. Click Finish. The New Project Information dialog box is displayed, It provides information you should review. 5. After reviewing the New Project Information dialog box, click OK.

Using the SDK Extension Wizard 2-5 Editing Sample Code in the .cpp File

Editing Sample Code in the .cpp File

After creating a project, you must edit the template code that the SDK Extension Wizard creates in the project_name.cpp file, where project_name is the name you assigned when you created a new project workspace. Each main function in this .cpp file requires some modification. “TODO” comments throughout the .cpp file flag the sections that you must change. Besides performing these mandatory changes, you can use MetaCube’s API to modify a .cpp file in any other way that suits your needs. Chapter 3, “MetaCube Class Library,” describes every class of object accessible through the SDK’s API. The following sections describe the major tasks when modifying a .cpp file:

■ Changing the Description of an Extension’s Arguments ■ Changing an Extension’s Argument Types ■ Validating the Type and Value of All Arguments ■ Creating the Necessary Process Code ■ Creating Multiple Extensions in a Snap-In The following sections include fragments of the harmonics.cpp file that illustrate the tasks you must perform. “Sample Extension’s Code” on page 2-21 shows the complete file after it has been modified to create an extension that calculates a harmonic moving average. In the .cpp file, the first function, DLLMAIN(), is automatically generated. It is used for initializing a .dll file for this Snap-In. This function does not require any modification.

Changing the Description of the Extension’s Arguments

In a .cpp file, the first major function, extension_name_Arguments(), provides a description of the extension’s arguments. This description is stored in the String Table in a project’s resource file. After a Snap-In has been built and successfully snapped into MetaCube Explorer, the description for each argument is displayed in the Measure Calculation dialog box, where it prompts the user for input.

2-6 SDK for Snap-Ins Programmer’s Manual Changing the Description of the Extension’s Arguments

Every extension requires at least one argument that identifies a measure on which a calculation is performed. The SDK Extension Wizard automatically generates template code providing a description of that argument. When an extension requires more than one argument, the SDK Extension Wizard generates template code that provides a default description for all additional arguments. The SDK Extension Wizard automatically generates a String Table that holds a description for each of the extension’s arguments. Within the String Table those descriptions are called “captions.” The default caption for the second and all subsequent arguments that the SDK Extension Wizard automatically generates is “Argument.” To customize the description of an argument so it accurately reflects the argument’s purpose, edit its caption in the String Table. For example, the caption for the second argument of the sample extension was changed from “Argument” to “Number of periods to harmonically average.” Limit the length of argument descriptions to 30 characters. If a text string describing an argument exceeds this limit, it may be truncated when Explorer displays it. Figure 4 provides a fragment of code that shows the TODO comment flagging the change you must make to the descriptions of an extension’s arguments.

Figure 4 void harmonicmovingavg_Arguments(CStringArray& results) ArgumentTypes { Function Before results.RemoveAll(); Editing

CString buf;

buf.LoadString(IDS_MEASURE_ARG); results.Add(buf);

//TODO - Change the descriptions of the Extension's Arguments

buf.LoadString(IDS_MCX_ARG); results.Add(buf); }

Using the SDK Extension Wizard 2-7 Changing the Extension’s Argument Types

Changing the Extension’s Argument Types

In a .cpp file, the second major function, extension_name_ArgumentTypes(), specifies argument types. You must correctly identify the type of each argument needed for the extension you are creating. The SDK Extension Wizard classifies all of the arguments it automatically generates as Names, but five argument types are possible. The extensions.h file for each project defines a constant for each of the possible argument types. Figure 5 lists those definitions for your convenience: Figure 5 // Constants Argument Type Constants #define EXT_ARG_NUMBER "Number" #define EXT_ARG_NAME "Name" #define EXT_ARG_TUPLE "Tuple" #define EXT_ARG_FUNCTION"Function" #define EXT_ARG_REPEAT "Repeat"

The argument types do the following: Number Indicates that the argument requires a number Name Indicates that the argument requires a name Tuple Indicates that the argument requires a pair of values. For example, a bucket that speciﬁes a range requires a pair of values: a lower bound and higher bound. Tuples should be entered in square brackets using the following format:

[ value1, value2 ]

Function Provides the text of a function call Repeat Provides a number specifying how many times the preceding action should be performed

2-8 SDK for Snap-Ins Programmer’s Manual Validating the Type and Value of All Arguments

You must edit the .cpp ﬁle to provide the correct argument type for the second and all subsequent arguments. For example, in the sample extension, the second argument is a Number rather than a Name. Figure 6 shows a fragment of code that includes the TODO comment ﬂagging the change you must make to the extension’s argument types:

Figure 6 void harmonicmovingavg_ArgumentTypes(CStringArray& results) ArgumentTypes { Function Before results.RemoveAll(); Editing results.Add(EXT_ARG_NAME);

//TODO - Change the types of the Extension's Arguments

results.Add(EXT_ARG_NAME); }

Figure 7 shows the same code fragment after the correct argument type (EXT_ARG_NUMBER) was inserted for the sample extension’s second argument and the TODO comment was deleted:

Figure 7 void harmonicmovingavg_ArgumentTypes(CStringArray& results) ArgumentTypes { Function After results.RemoveAll(); Editing results.Add(EXT_ARG_NAME); results.Add(EXT_ARG_NUMBER); }

Validating the Type and Value of All Arguments

In the .cpp file, the third major function, extension_name_Validate(), checks the data passed into the extension through its arguments. The code that is automatically generated for a .cpp file validates the type and value of data for the first argument. You should create code in the validate function to confirm that the type of data passed in for the second and all subsequent arguments is correct. For example, if an argument is a Number type, then you should write code that confirms that a number is passed in for that argument. You may also want to write code that checks the validity of all data that is passed in. For example, if an argument requires a number, you may want to confirm that the number lies within an acceptable range.

Using the SDK Extension Wizard 2-9 Validating the Type and Value of All Arguments

Figure 8 provides a fragment of code that shows the TODO comment ﬂagging the validate function:

Figure 8 Validate Function

BOOL harmonicmovingavg_Validate(class Query* query, class COlapObject* obj, class CParseNode* parse) { // Setup class Metabase* metabase = query->Get_m_metabase();

// OK, the format of this should be // HarmonicMovingAvg( measure | function(), ARGUMENTS)

if (parse->m_children.GetSize() != 2) return FALSE;

// Check the first arg...

CParseNode* first = parse->m_children[0];

if (first->m_type != CParseNode::NameType && first->m_type != CParseNode::FunctionType) return FALSE;

// Check the other arguments...

for (long i = 1; i < 2; ++i) { CParseNode* arg = parse->m_children[i];

// TODO - Place code here to validate the type and value of arg...

} return TRUE; }

2-10 SDK for Snap-Ins Programmer’s Manual Validating the Type and Value of All Arguments

In the sample extension, the second argument specifies the number of periods for which a harmonic moving average is calculated. In the .cpp file for the sample extension, the TODO comment in Figure 8 was replaced with two if statements. One confirms that data passed in for the second argument is a number; the other confirms that the value of the number passed in for the second argument is greater than or equal to 1. Figure 9 shows the lines of code that replace the TODO comment:

Figure 9 //*** checked that 2nd arg is a number Lines Inserted into if (arg->m_type != CParseNode::NumberType) the Validate return FALSE; Function //*** check that 2nd arg is >= 1 if (arg->m_number_val < 1) return FALSE;

Understanding the Validate Function

The validate function in the .cpp file takes three arguments: query, obj, and parse. The first argument identifies the Query object that contains the extension. The second argument specifies the QueryItem object that calls this extension. The last argument points to a CParseNode object, which provides the plan of attack for processing an extension. The CParseNode object is essentially a tree structure of CParseNode objects. The highest level object represents the function call to the extension itself. The CParseNode objects on the next level in the tree are children of the parent CParseNode object. Each child object on this level corresponds to one of the extension’s arguments. If those arguments consist of function calls, additional levels of CParseNode objects are necessary to represent those function calls. The validate function checks how many child objects of the parent CParseNode object have been passed to the extension. That number must match the number of arguments specified for the extension. In the sample extension, two arguments are specified, so the validate function includes the following code that confirms the presence of two CParseNode child objects:

if (parse->m_children.GetSize() != 2) return FALSE;

Using the SDK Extension Wizard 2-11 Creating the Process Code

Next the validate function checks the type of the first argument. The first argument may specify a query item that is a measure (in other words, a data value from a fact table, such as Units Sold), or it may include a recursive function call, such as a computation of a harmonic moving average or a percent change. The validate function confirms that the first argument is either a name, such as the name of a measure, or a function call. To perform this check, the sample extension includes the following code:

if (first->m_type != CParseNode::NameType && first->m_type != CParseNode::FunctionType) return FALSE; After making this check, the validate function loops through all of the other arguments to validate their type and value using the code you have written for that purpose.

Creating the Process Code

In the .cpp ﬁle, the process function, extension_name_Process(), does the actual work of an extension, performing calculations and changes on existing data and creating new values based on that data. The process function that is created automatically by the SDK Extension Wizard doubles the value of a cell. You must modify that code to create the functionality needed for your own extension. In the sample extension, the harmonic moving average is calculated for a number of periods speciﬁed by the user.

Understanding the Process Function

The process function in the .cpp file essentially consists of some initial set up and then three nested loops. All of this code is automatically generated by the SDK Extension Wizard. Together, the three loops cause the process to “walk” across all the cells in a virtual cube of data, essentially examining every cell in every row or column on every page and processing those cells affected by the extension. The first loop walks the pages of the cube, the second loop walks the rows or columns on each page, and the third loop walks the cells in each row or column, getting a value for each cell, changing that value as specified by the process code, and then putting a new value back into the cell.

2-12 SDK for Snap-Ins Programmer’s Manual Creating the Process Code

The ﬁrst and outermost loop in the process function walks all the pages in the virtual cube of data, determining the size of the page and the direction in which query items appear. Query items can be arranged on a page using either a column or row orientation. Figure 10 shows the loop in the .cpp ﬁle that walks the pages:

Figure 10 for (long page = 0; page < qcube->Get_m_numpages(); ++page) Loop Walking the { Pages in the // Get the bounds... Process Function long rows; long columns;

qcube->GetPageSize(page, rows, columns);

long max_dist;

if (column_orientation) max_dist = columns; else max_dist = rows; . . . }

The next loop walks across every column or row on a page. Figure 11 shows the loop in the .cpp ﬁle that walks every row or column:

Figure 11 for (long location = 0; location < max_dist; ++location) Loop Walking the { Row/Column in the // Now, walk and look for our row/column... Process Function long cell_index;

if (column_orientation) qcube->GetCellItemIndex(page, 0, location, cell_index); else qcube->GetCellItemIndex(page, location, 0, cell_index); . . . }

Using the SDK Extension Wizard 2-13 Creating the Process Code

The third loop walks every cell in a row or column and processes the data stored in that cell. Before the loop starts, an if statement performs a test to determine whether the query item for that row or column is one on which this function should operate:

// Is it me? if (cell_index == item_index) If the expression proves false—that is, if the query item for that row or column is not one on which the extension should operate—the process function skips that row or column. If the expression is true, the function walks the cells in that row or column, gets the value in each cell, performs the desired change or calculation, and puts a new value back into that cell. Typically, when you are customizing a .cpp ﬁle, this is the code that you will modify most extensively. It performs the work of your extension. Figure 12 shows code that the SDK Extension Wizard inserts into the .cpp ﬁle before the beginning of the third loop. This code includes the if statement testing the query item. Note that for the sample extension, code has been inserted here to declare two CArrays.

Figure 12 // Is it me? Code Before the Third Loop Begins if (cell_index == item_index) { // Yep...

// OK, now walk it and do it...

long walk_dist;

if (column_orientation) walk_dist = rows; else walk_dist = columns;

// Walk the cells and process them...

long position;

//*** storage for the cells to be averaged CArray harmonic_cells; CArray harmonic_cells_errors;

2-14 SDK for Snap-Ins Programmer’s Manual Creating the Process Code

Figure 13 shows the beginning of the third loop, which gets the value of each cell affected by the process function and the range of error associated with each cell. In any code that you write for the process function, you should create parallel structures like these, one for the value of a cell and one for the cell’s range of error. Error values are necessary when a query is performed on a sample table, which is a small but statistically accurate representation of a larger quantity of data. For more information on sample tables, see the MetaCube Explorer User’s Guide.

Figure 13 for (position = 0; position < walk_dist; ++position) Beginning of the { Third Loop SCell* cell_val = NULLP(SCell);

// Get the cell...

if (column_orientation) qcube->GetCell(page, position, location, cell_val); else qcube->GetCell(page, location, position, cell_val);

double old_val = 0; double old_error = 0;

if (cell_val) { old_val = cell_val->cell_value; old_error = cell_val->cell_error; } . . . }

Figure 14 shows the new code that was written for the process function in the sample extension. Note that this code sets the value of each cell and its range of error. The calculation of a harmonic moving average requires some special steps to accommodate negative values. Because you cannot derive the root of a negative number, the new code changes all negative values to positive. It then calculates the harmonic moving average of those cells and the range of error associated with each cell. Finally, if the original cell value was negative, the process function converts the value it has calculated into a negative number.

Using the SDK Extension Wizard 2-15 Creating the Process Code

Figure 14 Process Code Written for Sample Extension

//*** put old_val in the bucket...

harmonic_cells.Add(old_val); harmonic_cells_errors.Add(old_error);

//*** throw away the oldest if there are too many if (harmonic_cells.GetSize() > number_of_periods) { harmonic_cells.RemoveAt(0); harmonic_cells_errors.RemoveAt(0); }

//*** Compute the harmonic mean of them...

double val_product = 1; double error_product = 1;

for (long h_index = 0; h_index < harmonic_cells.GetSize(); ++h_index) { val_product = val_product * harmonic_cells[h_index]; error_product = error_product * harmonic_cells_errors[h_index]; }

BOOL val_negative = FALSE; BOOL error_negative = FALSE;

if (val_product < 0) { val_negative = TRUE; val_product = val_product * -1; }

if (error_product < 0) { error_negative = TRUE; error_product = error_product * -1; }

double new_val = exp(log(val_product) / harmonic_cells.GetSize()); double new_error = exp(log(error_product) / harmonic_cells.GetSize());

if (val_negative) new_val = new_val * -1;

if (error_negative) new_error = new_error * -1;

2-16 SDK for Snap-Ins Programmer’s Manual Creating Multiple Extensions in a Snap-In

Finally, the process function replaces the old values stored in the virtual cube of data with the new values it has derived and closes the loop. Figure 15 shows this code. For the sample extension, this portion of the code required no changes.

Figure 15 // Now, put it back... Close of Third Loop That Inserts New SCell new_value; Values Into Virtual // Preserve the formatting... Cube of Data if (cell_val) new_value = *cell_val;

// Store the values...

new_value.cell_value = new_val; new_value.cell_error = new_error;

// Put it in the cube...

if (column_orientation) qcube->SetCell(page, position, location, new_value); else qcube->SetCell(page, location, position, new_value); }

Creating Multiple Extensions in a Snap-In

A Snap-In can consist of multiple extensions. The template code generated by the SDK Extension Wizard creates one extension, but you can customize that code so it includes multiple extensions. To accomplish this, do the following:

■ Generate multiple headers ■ Generate parallel functions for each extension

Using the SDK Extension Wizard 2-17 Creating Multiple Extensions in a Snap-In

Generating Headers for Multiple Extensions

Header information for an extension appears at the end of the .cpp ﬁle. If the ﬁle contains only one extension, the header information that was automatically generated by the SDK Extension Wizard is correct. Figure 16 shows the header block for the sample extension:

Figure 16 // Register the functions... Header Block for Sample Extension // HarmonicMovingAvg - QueryItem...

CIExtension* harmonicmovingavg_ext = new CIExtension; entry->m_extensions.Add(harmonicmovingavg_ext); meta->Get_m_extensions().Add(harmonicmovingavg_ext);

// Set up the header

harmonicmovingavg_ext->m_type = CIExtension::QueryItemType; harmonicmovingavg_ext->m_name = "HarmonicMovingAvg";

// Set up the entry points... harmonicmovingavg_ext->m_validate = harmonicmovingavg_Validate; harmonicmovingavg_ext->m_processitem = harmonicmovingavg_Process; harmonicmovingavg_ext->m_arguments = harmonicmovingavg_Arguments; harmonicmovingavg_ext->m_argumenttypes = harmonicmovingavg_ArgumentTypes;

If the .cpp ﬁle contains multiple extensions, you must create an additional header block for each extension. To do that, copy and paste the lines shown above and edit the data in those lines to match each of the additional extensions. Figure 16 shows a header block that has been created for a second extension called “statmove”:

Figure 17 // Register the functions... Header Block for Second Extension // HarmonicMovingAvg - QueryItem...

CIExtension* statmove_ext = new CIExtension; entry->m_extensions.Add(statmove_ext); meta->Get_m_extensions().Add(statmove_ext);

// Set up the header statmove_ext->m_type = CIExtension::QueryItemType; statmove_ext->m_name = "STATMOVE"; // Set up the entry points... statmove_ext->m_validate = statmove_Validate; statmove_ext->m_processitem = statmove_Process; statmove_ext->m_arguments = statmove_Arguments; statmove_ext->m_argumenttypes = statmove_ArgumentTypes;

2-18 SDK for Snap-Ins Programmer’s Manual Building and Testing an Extension

Generating Functions for Multiple Extensions

The .cpp ﬁle generated by the SDK Extension Wizard includes code for one extension. If you want a Snap-In to contain multiple extensions, you must duplicate the ﬁle’s four main functions (Argument, ArgumentType, Validate, and Process) for each extension. Each function must be renamed where appropriate. For example, in the sample extension, the Argument function is called harmonicmovingavg_Argument(). If a second extension called “statmove” is added, the Argument function for the statmove extension would be called statmove_Argument(). Of course, all code necessary to implement the functionality of the second extension must also be changed.

Building and Testing an Extension

When you have finished writing the code for a .cpp file, use Microsoft Developer Studio to build and test an .mcx file, which represents the actual Snap-In. The following procedures describe the steps necessary for building and testing an .mcx file. To build a pre-release .mcx file:

1. Use the drop-down list on Microsoft Developer Studio’s toolbar to set the default project conﬁguration. The drop-down list includes two options: Win32 Debug or Win32 Release. While testing a Snap- In, set the project conﬁguration to Win32 Debug. 2. Build a project and resolve all build errors. To run MetaCube in the Developer Studio debugging environment:

1. In Microsoft Developer Studio, click Settings... in the Project menu. 2. On the Project Settings dialog box, click the Debug tab. 3. In the Executable for debug session text box, enter the full path and ﬁle name of the executable code for the target application and then click OK. For example, if you want run the new extension in MetaCube Explorer, enter a path to Explorer’s executable code, such as c:\MetaCube\expl32.exe. If you want to run the new extension in MetaCube for Excel, enter a path to Excel’s executable. Note: You cannot use MetaCube Web Explorer to debug new extensions.

Using the SDK Extension Wizard 2-19 Building and Testing an Extension

4. Click Go. Microsoft Developer Studio runs the targeted application and the MetaCube analysis engine within the Developer Studio’s debugging environment. To snap an extension into Explorer:

1. Invoke MetaCube as described above. Then start Explorer, which will connect to the instance of MetaCube running in the Developer Studio’s debugging environment. 2. In Explorer, click Snap-Ins... in the Tools menu. 3. From the Snap-In Manager dialog box, click Add. 4. From the Add Extension dialog box, select the name of the extension (the sample extension appears as HarmonicMovingAvg) and click OK. To test and debug an extension:

1. After invoking Explorer within the Microsoft debugging environment, run a query that uses the new extension. For more information on creating queries, see the MetaCube Explorer User’s Guide. 2. Verify the results generated by the new query. If software problems exist, modify the extension’s functionality in the .cpp file, re-compile the file, and test it again in Explorer. After an extension has been snapped into Explorer once, you do not have to snap it in again. To build a final .mcx file:

Use the drop-down list on Microsoft Develop Studio’s toolbar to set the default project conﬁguration to Win32 Release. Build the project, which generates a new .mcx ﬁle, and the new extension is ready for release.

2-20 SDK for Snap-Ins Programmer’s Manual Sample Extension’s Code

Sample Extension’s Code

This section shows the complete text of the ﬁnal harmonics.cpp ﬁle. All the code necessary to perform a harmonic moving average has been inserted, replacing the template’s original code that doubled the value of a measure. Any changes made to a line of template code are highlighted with a heavy gray bar ( ) to the left of that line.

// harmonics.cpp : Defines the initialization routines for the DLL. //

#include "stdafx.h" #include #include

#ifdef _DEBUG #define new DEBUG_NEW #undef THIS_FILE static char THIS_FILE[] = __FILE__; #endif static AFX_EXTENSION_MODULE HarmonicsDLL = { NULL, NULL }; extern "C" int APIENTRY DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) { if (dwReason == DLL_PROCESS_ATTACH) { TRACE0("HARMONICS.DLL Initializing!\n");

// Extension DLL one-time initialization AfxInitExtensionModule(HarmonicsDLL, hInstance);

// Insert this DLL into the resource chain new CDynLinkLibrary(HarmonicsDLL); } else if (dwReason == DLL_PROCESS_DETACH) { TRACE0("HARMONICS.DLL Terminating!\n"); } return 1; // ok }

Using the SDK Extension Wizard 2-21 Sample Extension’s Code

void harmonicmovingavg_Arguments(CStringArray& results) { results.RemoveAll();

CString buf;

buf.LoadString(IDS_MEASURE_ARG); results.Add(buf); //*** edited resource string table, removed comment buf.LoadString(IDS_MCX_ARG); results.Add(buf); }

void harmonicmovingavg_ArgumentTypes(CStringArray& results) { results.RemoveAll(); results.Add(EXT_ARG_NAME); //*** changed type from name to number results.Add(EXT_ARG_NUMBER); }

BOOL harmonicmovingavg_Validate(class Query* query, class COlapObject* obj, class CParseNode* parse) { // Setup class Metabase* metabase = query->Get_m_metabase();

// OK, the format of this should be // HarmonicMovingAvg( measure | function(), ARGUMENTS)

if (parse->m_children.GetSize() != 2) return FALSE;

// Check the first arg...

CParseNode* first = parse->m_children[0];

if (first->m_type != CParseNode::NameType && first->m_type != CParseNode::FunctionType) return FALSE;

// Check the other arguments... for (long i = 1; i < 2; ++i) { CParseNode* arg = parse->m_children[i];

//*** checked that 2nd arg is a number if (arg->m_type != CParseNode::NumberType) return FALSE;

//*** check that 2nd arg is >= 1 if (arg->m_number_val < 1) return FALSE; }

return TRUE; }

2-22 SDK for Snap-Ins Programmer’s Manual Sample Extension’s Code

void harmonicmovingavg_Process(class Query* query, class QueryItem* item, class CParseNode* parse) { // OK, first, find the direction...

ASSERT(parse->m_children.GetSize() == 2);

//***Get number of periods asked for

CParseNode* arg = parse->m_children[1];

long number_of_periods = long(arg->m_number_val);

// Get my index from the collection...

LPDISPATCH itemdisp = query->GetQueryItems(); QueryItems* items = (QueryItems*)query->FromIDispatch(itemdisp);

long item_index = items->GetElementIndex(item->GetIDispatch(FALSE));

// OK, now get our rows/columns

CQueryCube* qcube = query->Get_m_qcube();

BOOL column_orientation = FALSE; if (query->Get_m_itemOrientation() == OrientationColumn) column_orientation = TRUE;

long page_dims; long row_dims; long col_dims;

qcube->GetDimCounts(page_dims, row_dims, col_dims);

// Get the key for this query item...

for (long page = 0; page < qcube->Get_m_numpages(); ++page) { // Get the bounds... long rows; long columns;

qcube->GetPageSize(page, rows, columns); long max_dist;

if (column_orientation) max_dist = columns; else max_dist = rows;

Using the SDK Extension Wizard 2-23 Sample Extension’s Code

for (long location = 0; location < max_dist; ++location) { // Now, walk and look for our row/column...

long cell_index;

if (column_orientation) qcube->GetCellItemIndex(page, 0, location, cell_index); else qcube->GetCellItemIndex(page, location, 0, cell_index);

// Is it me?

if (cell_index == item_index) { // Yep...

// OK, now walk it and do it...

long walk_dist;

if (column_orientation) walk_dist = rows; else walk_dist = columns;

// Walk the cells and process them...

long position;

//*** storage for the cells to be averaged CArray harmonic_cells; CArray harmonic_cells_errors;

for (position = 0; position < walk_dist; ++position) { SCell* cell_val = NULLP(SCell);

// Get the cell...

if (column_orientation) qcube->GetCell(page, position, location, cell_val); else qcube->GetCell(page, location, position, cell_val);

double old_val = 0; double old_error = 0;

if (cell_val) { old_val = cell_val->cell_value; old_error = cell_val->cell_error; }

2-24 SDK for Snap-Ins Programmer’s Manual Sample Extension’s Code

//*** put old_val in the bucket... harmonic_cells.Add(old_val); harmonic_cells_errors.Add(old_error);

//*** throw away the oldest if there are too many if (harmonic_cells.GetSize() > number_of_periods) { harmonic_cells.RemoveAt(0); harmonic_cells_errors.RemoveAt(0); }

//*** Compute the harmonic mean of them... double val_product = 1; double error_product = 1; for (long h_index = 0; h_index < harmonic_cells.GetSize(); ++h_index) { val_product = val_product * harmonic_cells[h_index]; error_product = error_product * harmonic_cells_errors[h_index]; }

BOOL val_negative = FALSE; BOOL error_negative = FALSE; if (val_product < 0) { val_negative = TRUE; val_product = val_product * -1; } if (error_product < 0) { error_negative = TRUE; error_product = error_product * -1; } double new_val = exp(log(val_product) / harmonic_cells.GetSize()); double new_error = exp(log(error_product) / harmonic_cells.GetSize()); if (val_negative) new_val = new_val * -1; if (error_negative) new_error = new_error * -1;

Using the SDK Extension Wizard 2-25 Sample Extension’s Code

// Now, put it back...

SCell new_value;

// Preserve the formatting... if (cell_val) new_value = *cell_val;

// Store the values...

new_value.cell_value = new_val; new_value.cell_error = new_error;

// Put it in the cube...

if (column_orientation) qcube->SetCell(page, position, location, new_value); else qcube->SetCell(page, location, position, new_value); } } } } }

// Global DLL Initialization Hook...

void DllHookPlug(CPlugIn* entry, class Metabase* meta, long cube_version) { if (cube_version != MCXSDK_VERSION) throw COlapException(ERR_MCX_VERSION);

entry->m_metabase = meta;

// Register the functions...

// HarmonicMovingAvg - QueryItem... CIExtension* harmonicmovingavg_ext = new CIExtension; entry->m_extensions.Add(harmonicmovingavg_ext); meta->Get_m_extensions().Add(harmonicmovingavg_ext);

// Set up the header

harmonicmovingavg_ext->m_type = CIExtension::QueryItemType; harmonicmovingavg_ext->m_name = "HarmonicMovingAvg";

// TODO - Put a second extension header block here to have // HARMONICS.MCX expose a second extension. }

2-26 SDK for Snap-Ins Programmer’s Manual Chapter MetaCube Class Library Reference 3

CDb...... 3-3 CDimKey ...... 3-18 CIExtension ...... 3-28 CMetaObject ...... 3-33 COlapException ...... 3-39 COlapObject ...... 3-41 COleCollection ...... 3-46 CParseNode ...... 3-59 CPlugIn...... 3-64 CQueryCube ...... 3-66 CSelect ...... 3-95 Extension ...... 3-98 Extensions ...... 3-109 Filter ...... 3-112 FilterElement ...... 3-121 FilterElements ...... 3-128 Filters ...... 3-132 Folder ...... 3-139 Folders ...... 3-146 Metabase ...... 3-150 MetaCube ...... 3-189 MetaCubes ...... 3-224 Queries ...... 3-227 Query ...... 3-230 QueryBackJob...... 3-261 QueryBackJobs ...... 3-274 QueryCategories...... 3-277 QueryCategory ...... 3-284 QueryItem ...... 3-297 QueryItems ...... 3-311 Summaries ...... 3-317 Summary ...... 3-324 ValueList ...... 3-330

3-2 SDK for Snap-Ins Programmer’s Manual his chapter describes the MetaCube class library that is accessible Tthrough the SDK. For every class, this chapter provides a hierarchy chart, a summary list of the possible member functions and data members, and a detailed description of each member function and data member.

CDb

CObject

CDb

Objects of the CDb class embody database connections. By calling the CDb member functions, you can submit SQL statements to a database and obtain information about tables that the database contains.

MetaCube Class Library 3-3 CDb Class Members

CDb Class Members

Operations

Commit Conﬁrms changes that have been made to a database (if the database has logging turned on)

DeleteString Deletes a string stored by PutString()

EndSelect Destroys the CSelect object created by the SelectStmt() member function

ExecuteStmt Executes two types of non-SELECT SQL statements: one allows you to incorporate runtime arguments; the other does not.

GetColumns Retrieves information about tables owned by a particular user in a database

GetDataSources Retrieves information about ODBC data sources.

GetString Points a reference to a string stored by PutString()

GetTables Points a reference to a CStringArray containing a list of the tables owned by a particular user or schema in the database

GetUsers Point a reference to a CStringArray containing a list of the users or schemas in a database

PutString Stores a string of any size and returns an identifying integer for that string

Rollback Revokes changes that have been made to a database (if the database has logging turned on)

SelectStmt Executes an SQL statement that performs a query, returning a handle to a CSelect object. The SQL statement executed with this member function can require runtime arguments

3-4 SDK for Snap-Ins Programmer’s Manual CDb::Commit

CDb::Commit

void Commit();

Remarks

Call this member function to conﬁrm changes that have been made to a database. If a database does not have logging turned on, changes made to that database take effect as soon as a statement executes. For those types of databases, the Commit() function is unnecessary.

CDb::DeleteString

void DeleteString( long msgid );

Parameters msgid The integer returned by PutString() identifying a string stored by that member function

Remarks

Call this member function to delete a string stored by calling PutString(). The PutString() member function can store a string of any length, which allows you to circumvent the Informix limit of 2,000 characters in database columns.

MetaCube Class Library 3-5 CDb::EndSelect

CDb::EndSelect

void EndSelect( CSelect* select );

Parameters

select Speciﬁes the CSelect object to be destroyed.

Remarks

Call this member function to destroy the CSelect object created by the SelectStmt() member function after all necessary information has been obtained from the CSelect object.

3-6 SDK for Snap-Ins Programmer’s Manual CDb::ExecuteStmt (for non-SELECT SQL syntax requiring no runtime arguments)

CDb::ExecuteStmt (for non-SELECT SQL syntax requiring no runtime arguments)

void ExecuteStmt( LPCSTR stmt, long* nrows = (long*)0 );

Parameters stmt A character string that provides the SQL statement to be executed. nrows An optional argument that points to the number of rows that were processed by the SQL statement, such as the number of rows that were deleted. If a value is not deﬁned for nrows, it defaults to a null pointer.

Remarks

Call this member function to execute a non-SELECT SQL statement, such as CREATE TABLE or DROP TABLE, that does not require runtime arguments. To execute a non-SELECT SQL statement requiring runtime arguments, see “CDb::ExecuteStmt (for non-SELECT SQL syntax requiring runtime arguments)” on page 3-8. To execute an SQL SELECT statement, see “CDb::SelectStmt” on page 3-16.

MetaCube Class Library 3-7 CDb::ExecuteStmt (for non-SELECT SQL syntax requiring runtime arguments)

CDb::ExecuteStmt (for non-SELECT SQL syntax requiring runtime arguments)

void ExecuteStmt( LPCSTR stmt, long nbinds, long* types, void** values, long* sizes = (long*)0, long** nulls = (long**)0, long iters = 1, long* nrows = (long*)0 );

Parameters

stmt A character string that provides an SQL statement to be executed

nbinds A long integer that equals the number of arguments to be bound into the SQL statement (that is, the number of question marks the SQL statement employs). The following example shows an SQL statement that requires two arguments: INSERT INTO EMP VALUES (?, ?) The number speciﬁed for nbinds determines the number of values that must be passed in for the types, values, sizes, and nulls arguments. For example, if nbinds equals three, the length of the array for the types, values, sizes, and nulls arguments must be three.

types A pointer to a long integer or an array of constants specifying the data type for an argument. The cdb.h ﬁle deﬁnes a name and constant for each of the possible data types. They are:

Name Constant Data Type

DB_CHAR 1 char* DB_NUM 2 long DB_FLOAT 3 ﬂoat DB_DOUBLE 4 double

values An array of pointers to the values used as input by ExecuteStmt(). This array can point to arrays of character strings, numbers, or mixtures of both. When specifying strings for an array, use char*.

sizes An optional argument providing an array of integers used to specify the size of strings. If the size speciﬁed with this argument is smaller than the string actually placed into an array, the string will be truncated.

3-8 SDK for Snap-Ins Programmer’s Manual CDb::ExecuteStmt (for non-SELECT SQL syntax requiring runtime arguments)

nulls An optional argument providing an array of pointers to constants that provide null flags. Null flags designate values as null values or not null values. A null flag causes the values stored in the arrays specified with the values argument to be ignored and to be replaced by null. The null flag takes precedence over a value stored in the arrays specified with the values argument. The sdk.h file includes a macro for creating an array of nulls. The cdb.h file defines a name and constant for each of the null flags. They are:

Name Constant Description

DB_NULL -1 SQL_NULL_DATA DB_NNULL -3 SQL_NTS iters A long integer specifying the number of iterations for this statement. By inserting arrays of values for the types, values, sizes, and nulls parameters, ExecuteStmt() can run repeatedly, inserting the next set of values from the appropriate array every time it executes. The default value for iters is 1. nrows An optional argument pointing to the number of rows that were processed by the SQL statement. If a value is not deﬁned for nrows, it defaults to a null pointer.

Remarks

Call this member function to execute a non-SELECT SQL statement that requires runtime arguments. To execute a non-SELECT SQL statement that does not require runtime arguments, see “CDb::ExecuteStmt (for non- SELECT SQL syntax requiring no runtime arguments)” on page 3-7. To execute an SQL SELECT statement, see “CDb::SelectStmt” on page 3-16.

MetaCube Class Library 3-9 CDb::GetColumns

CDb::GetColumns

void GetColumns( CString& schema, CString& table, CStringArray& results, CLongArray& types, long maxrows = 1000 );

Parameters

schema A reference to a CString object containing the names of schemas or users returned by GetUsers()

table A reference to a CString object containing the name of a table returned by GetTables()

results A reference to an array of CString objects that will be ﬁlled with the names of the columns in the table speciﬁed with the schema and table arguments.

types A reference to an array of long objects that will be filled with constants specifying the data type for each column. The sdk.h file defines a CLongArray as a kind of CArray containing longs. The cdb.h file defines a name and constant for each of the possible data types that might be listed in this array. They are:

Name Constant Data Type

DB_CHAR 1 char* DB_NUM 2 long DB_FLOAT 3 ﬂoat DB_DOUBLE 4 double

maxrows The maximum size allowed for the array speciﬁed with the results argument. If not speciﬁed, the maximum is 1000 rows.

Remarks

Call this member function to retrieve information about a table owned by a particular user or schema in the database. This function points references to arrays ﬁlled with the names of a table’s columns and the data type for each column.

3-10 SDK for Snap-Ins Programmer’s Manual CDb::GetDataSources

CDb::GetDataSources

void GetDataSources( CStringArray& results, long maxrows = 1000 );

Parameters results A reference to an array of CString objects that will be filled with the ODBC datasource names configured for the computer where the MetaCube analysis engine is running. maxrows The maximum size allowed for the array specified with the results argument. If not specified, the maximum is 1000 rows.

Remarks

Call this member function to retrieve information about ODBC datasources. This function retrieves references to arrays ﬁlled with the names of ODBC datasources conﬁgured for the computer where the MetaCube analysis engine is running.

MetaCube Class Library 3-11 CDb::GetString

CDb::GetString

void GetString( long msgid, CString& str );

Parameters

msgid The integer returned by PutString() identifying a string stored by that member function

str A reference that returns a CString ﬁlled with the string stored by the PutString() member function

Remarks

Call GetString() to point a reference to a string stored by PutString(). The Informix database limits column lengths. For example, character-type columns are limited to 2,000 characters. To avoid this limitation and store strings of any arbitrary size, use the PutString() and GetString() member functions.

3-12 SDK for Snap-Ins Programmer’s Manual CDb::GetTables

CDb::GetTables

void GetTables( CString& schema, CStringArray& results, long maxrows = 1000 );

Parameters schema A reference to a CString containing the name of the schema or user returned by GetUsers(). results A reference that returns an array of CString objects filled with names of the tables grouped with the user or schema specified by the schema argument. maxrows The maximum size allowed for the array specified with the results argument. If not specified, the maximum is 1000 rows.

Remarks

Call this member function to point a reference to a CStringArray containing a list of the tables owned by a particular user or schema in the database.

MetaCube Class Library 3-13 CDb::GetUsers

CDb::GetUsers

void GetUsers( CStringArray& results, long maxrows = 1000 );

Parameters

results A reference that returns an array of CString objects ﬁlled with the names of the users or schemas in the database.

maxrows The maximum size allowed for the array speciﬁed with the results argument. If not speciﬁed, the maximum is 1000 rows.

Remarks

Call this member function to point a reference to a CStringArray containing a list of the users or schemas in a database.

3-14 SDK for Snap-Ins Programmer’s Manual CDb::PutString

CDb::PutString

long PutString( CString& str );

Return Value

A long integer identifying a string that has been stored.

Parameters str A reference to a string of any length

Remarks

Call PutString() to store a string of any size. The member function returns an identifying integer for the string it stores. Call GetString() to point a reference to the string stored with PutString(). The Informix database limits column lengths. For example, character-type columns are limited to 2,000 characters. To avoid this limitation, use the PutString() and GetString() member functions.

CDb::Rollback

void Rollback();

Remarks

Call this member function to undo changes that have been made to a database. If a database does not have logging turned on, changes made to that database take effect as soon as a statement executes. For those types of databases, the Rollback() function has no effect.

MetaCube Class Library 3-15 CDb::SelectStmt

CDb::SelectStmt

CSelect* SelectStmt( LPCSTR stmt, long nbinds, long* types, void** values, long rows = 1, long* sizes = (long*)0 Query* = NULLP(Query) );

Return Value

A pointer to a CSelect object containing the results of an SQL query.

Parameters

stmt A character string that provides an SQL statement to be executed.

nbinds A long integer that equals the number of arguments to be bound into the SQL statement (that is, the number of question marks the SQL statement employs). The number speciﬁed for nbinds determines the number of values that must be passed in for the types, values, and sizes arguments. For example, if nbinds equals three, the length of the array for the types, values, and sizes arguments must be three.

types A pointer to an array of constants specifying the data types for an argument. The cdb.h ﬁle deﬁnes a name and constant for each of the possible data types. They are:

Name Constant Data Type

DB_CHAR 1 char* DB_NUM 2 long DB_FLOAT 3 ﬂoat DB_DOUBLE 4 double

values An array of pointers to values, such as an array of character strings, numbers, or mixtures of both. Put a char* into this array to specify a string.

rows A long integer that speciﬁes how many rows at a time should be retrieved. If not speciﬁed, the default value for this argument is 1 row.

3-16 SDK for Snap-Ins Programmer’s Manual CDb::SelectStmt

sizes An optional argument providing an array of integers used to change the size of strings. By default, character strings are null- terminated, longs are 4 bytes, ﬂoats are 4 bytes, and doubles are 8 bytes. If the size speciﬁed with this argument is too small for a string put into an array, the string will be truncated.

Query An optional argument providing a pointer to the Query object for the query that is being performed. Specifying a pointer with this argument is necessary if the query is asynchronous and the asynchronous query may have to be canceled. If this argument is not speciﬁed, its default value is a macro generating a null pointer.

Remarks

Call this member function to execute an SQL statement that performs a query, returning values or other information. The SQL statement submitted with this member function can require runtime arguments. When SelectStmt() is executed, it returns a handle to a CSelect object, from which the results of the query can be obtained using the CSelect member functions. After you have obtained all necessary information from a CSelect object, call the EndSelect() member function to destroy the CSelect object. To execute a non-SELECT SQL statement rather than an SQL statement that performs a query, see “CDb::ExecuteStmt (for non-SELECT SQL syntax requiring no runtime arguments)” on page 7 or “CDb::ExecuteStmt (for non- SELECT SQL syntax requiring runtime arguments)” on page 8.

MetaCube Class Library 3-17 CDimKey

CDimKey

CObject

CDimKey

A QueryCube is a multi-dimensional cube of data. Data points within the cube store values for the query’s measures. Along the various axes of the cube are points known as dimension keys. Each CDimKey object represents a dimension key. For example, on a QueryCube dimension that provides brand information, each different brand, such as Alden, Barton, or Delmore, is a dimension key, and each would be represented by a different CDimKey object. Dimension keys can be sorted alphabetically or they can use numeric sorting schemes. Dimension keys can also be grouped. Within each group, the dimension keys are sorted using either an alphabetic or numeric scheme.

3-18 SDK for Snap-Ins Programmer’s Manual CDimKey Class Members

CDimKey Class Members

Operations

CDimKey Constructs a CDimKey object using two possible techniques: one requires you to supply arguments that deﬁne the CDimKey object; the other is a copy constructor that copies the value of one CDimKey object to create a new CDimKey object.

Hash Returns a number for a CDimKey object that is almost certainly unique and can be used for quick comparisons operator> Determines if a CDimKey object is greater than this CDimKey object operator< Determines if a CDimKey object is less than this CDimKey object operator== Determines if a CDimKey object is equal to this CDimKey object

SetFrom Sets the value of an existing CDimKey object by using the value of another CDimKey object

Data Members m_group Assigns a numeric value that is used to group attributes m_selfsort Determines whether dimension keys should be sorted by the value of m_string or m_sortval m_sortval Provides a numeric value that is used to sort dimension keys when m_selfsort is zero m_string Provides a string representation (typically the name) of the value of a dimension key

MetaCube Class Library 3-19 CDimKey::CDimKey

CDimKey::CDimKey

CDimKey ( LPCTSTR string, long group = 0, BOOL selfsort = TRUE, long sortval = 0 ); CDimKey ( CDimKey& source );

Parameters

string A mandatory argument providing a string that is the value of a dimension key

group An optional argument providing a value for m_group for a CDimKey object. If no value is speciﬁed for this argument, the value of m_group for this CDimKey object will default to 0.

selfsort An optional argument specifying a value for m_selfsort for a CDimKey object. If no value is speciﬁed for this argument, the value of m_selfsort for this CDimKey object will default to TRUE.

sortval An optional argument specifying a numeric sorting value for a CDimKey object. If no value is speciﬁed for this argument, the value of m_sortval for this CDimKey object will default to 0.

source A reference to a CDimKey object that is copied to construct a new CDimKey object.

Remarks

Call either of these constructor member functions to construct a CDimKey object. One version of CDimKey() requires you to supply arguments that deﬁne the CDimKey object. The other version of CDimKey() is a copy constructor that copies the value of one CDimKey object to create a new CDimKey object.

3-20 SDK for Snap-Ins Programmer’s Manual CDimKey::Hash

CDimKey::Hash

UINT Hash();

Return Value

An unsigned integer.

Remarks

Call this member function to return a number representing a CDimKey object that is almost certainly unique. Numbers returned by this member function can be used to compare CDimKey objects rapidly.

CDimKey::m_group

long m_group;

Remarks

This data member assigns a numeric value that is used to group dimension keys. For example, if the Brand attribute is assigned a value of 1 and all other Product attributes are assigned a value of 2, all Brand data points are listed on a QueryCube axis ﬁrst and then all other Product data points are listed second. Within each group, dimension keys are sorted using the method speciﬁed by the m_selfsort data member.

MetaCube Class Library 3-21 CDimKey::m_selfsort

CDimKey::m_selfsort

Bool m_selfsort;

Remarks

This data member provides a Boolean value. Nonzero indicates that dimension keys should be sorted by the value of the m_string data member. Zero indicates that they should be sorted by the number stored in the m_sortval data member.

CDimKey::m_sortval

long m_sortval;

Remarks

This data member provides a numeric value that is used to sort dimension keys when m_selfsort is set to zero. In MetaCube Warehouse Manager, you can specify a numeric column whose values are used to sort corresponding attribute values. For example, a column that associates a number with the name of each month (1 for January, 2 for February, and so forth) allows you to sort month names in chronological order. If a column of numeric values is used for sorting attribute values, each particular number is assigned to a CDimKey object using the m_sortval data member.

3-22 SDK for Snap-Ins Programmer’s Manual CDimKey::m_string

CDimKey::m_string

CString m_string;

Remarks

This data member provides a string representation (typically the name) of a dimension key. Each CDimkey object represents a value on a QueryCube’s axis. For example, if the ﬁrst three points on the Brand axis were Alden, Barton, and Delmore, the value of m_string for the ﬁrst dimension key would be Alden, the second would be Barton, and the third Delmore.

MetaCube Class Library 3-23 CDimKey::operator>

CDimKey::operator>

BOOL operator>( CDimKey& operand );

Return Value

A Boolean value. Nonzero indicates the CDimKey object supplied as an argument is greater than the value of this CDimKey object. Zero indicates the CDimKey supplied as an argument is not greater than this CDimKey object.

Parameters

operand A reference to a CDimKey object

Remarks

Call this overloaded operator function to determine if a CDimKey object is greater than this CDimKey object.

Example

class CDimKey Key1; class CDimKey Key2; . . . if (Key1 > Key2); . . .

3-24 SDK for Snap-Ins Programmer’s Manual CDimKey::operator<

CDimKey::operator<

BOOL operator<( CDimKey& operand );

Return Value

A Boolean value. Nonzero indicates the CDimKey object supplied as an argument is less than the value of this CDimKey object. Zero indicates the CDimKey supplied as an argument is not less than this CDimKey object.

Parameters operand A reference to a CDimKey object

Remarks

Call this overloaded operator function to determine if a CDimKey object is less than this CDimKey object.

Example

class CDimKey Key1; class CDimKey Key2; . . . if (Key1 < Key2); . . .

MetaCube Class Library 3-25 CDimKey::operator==

CDimKey::operator==

BOOL operator==( CDimKey& operand );

Return Value

A Boolean value. Nonzero indicates the CDimKey object supplied as an argument is equal to the value of this CDimKey object. Zero indicates the CDimKey supplied as an argument is not equal to this CDimKey object.

Parameters

operand A reference to a CDimKey object

Remarks

Call this overloaded operator function to determine if a CDimKey object is equal to this CDimKey object.

Example

class CDimKey Key1; class CDimKey Key2; . . . if (Key1 == Key2); . . .

3-26 SDK for Snap-Ins Programmer’s Manual CDimKey::SetFrom

CDimKey::SetFrom

void SetFrom( CDimKey& source );

Parameters source A reference to a CDimKey object

Remarks

Call this member function to set the value of an existing CDimKey object by using the value of another CDimKey object. Unlike CDimKey(), this member function does not create a new CDimKey object.

MetaCube Class Library 3-27 CIExtension

CIExtension

CObject

CIExtension

A CIExtension object describes one of the extensions in a Snap-In (an .mcx file) to the MetaCube engine. The .cpp file used to create a Snap-In should contain a header block of code identifying each extension included in the Snap-In. That header block creates a CIExtension object for each extension in the Snap-In and hands that CIExtension object to the MetaCube engine. Do not confuse a CIExtension object with an Extension object. An Extension object embodies a Snap-In (an .mcx file) while a CIExtension object represents a utility contained within a Snap-In, such as the harmonic moving average. A Snap-In may contain multiple utilities.

CIExtension Class Members

Operations

m_arguments Points to an extension_name_Arguments() function in the .cpp ﬁle for a Snap-In

m_argumenttypes Points to an extension_name_ArgumentTypes() function in the .cpp ﬁle for a Snap-In

m_name Provides the name of an extension

m_processitem Provides a pointer to an extension_name_Process() function in the .cpp ﬁle for a Snap-In

m_validate Provides a pointer to an extension_name_Validate() function in the .cpp ﬁle for a Snap-In

3-28 SDK for Snap-Ins Programmer’s Manual CIExtension::m_arguments

CIExtension::m_arguments

void (*m_arguments)(CStringArray& results);

Parameters results A reference to the CStringArray to be ﬁlled in by the extension_name_Arguments() function in the .cpp ﬁle for this Snap-In

Remarks

This data member points a reference to an extension_name_Arguments() function in the .cpp ﬁle for a Snap-In, where extension_name is the name assigned to an extension with the SDK Extension Wizard. The extension_name_Arguments() function provides descriptions of all the arguments needed for an extension. Those descriptions are typically stored in the String Table in a project’s resource ﬁle.

MetaCube Class Library 3-29 CIExtension::m_argumenttypes

CIExtension::m_argumenttypes

void (*m_argumenttypes)(CStringArray& results);

Parameters

results A reference to the CStringArray to be ﬁlled in by the extension_name_ArgumentTypes() function in the .cpp ﬁle for this Snap-In

Remarks

This data member points a reference to an extension_name_ArgumentTypes() function in the .cpp ﬁle for a Snap-In, where extension_name is the name assigned to an extension with the SDK Extension Wizard. The extension_name_ArgumentTypes() function classiﬁes the types of all the arguments needed for an extension.

CIExtension::m_name

CString m_name;

Remarks

This data member is a CString that provides the name of an extension. The name is assigned when you invoke the SDK Extension Wizard to create a .cpp ﬁle.

3-30 SDK for Snap-Ins Programmer’s Manual CIExtension::m_processitem

CIExtension::m_processitem

void (*m_processitem)(class Query* query, class QueryItem* item, class CParseNode* parse);

Parameters query The pointer to the Query object that is using this extension item The pointer to the QueryItem representing the measure on which this extension operates parse The pointer to the CParseNode object that provides the plan needed for processing this extension

Remarks

This data member stores a pointer to an extension_name_Process() function in the .cpp ﬁle for a Snap-In, where extension_name is the name assigned to an extension with the SDK Extension Wizard. The extension_name_Process() function determines which cells in a virtual cube of data are affected by the extension, performs changes and calculations to those cells, and inserts new values into cells.

CIExtension::m_type

enum {QueryCategoryType, QueryItemType} m_type;

Remarks

This data member is an enumerated type, which provides a ﬂag indicating whether an extension performs its function on a QueryItem or a QueryCat- egory object.

MetaCube Class Library 3-31 CIExtension::m_validate

CIExtension::m_validate

BOOL (*m_validate)(class Query* query, class COlapObject* obj, class CParseNode* parse);

Return Value

A Boolean value. Nonzero indicates the data passed into an extension through its arguments is valid. Zero indicates that the data passed in is not valid.

Parameters

query The pointer to the Query object that is using this extension

obj The pointer to either the QueryItem or QueryCategory object that calls this extension

parse The pointer to the CParseNode object that provides the plan needed for processing this extension

Remarks

This data member stores a pointer to an extension_name_Validate() function in the .cpp ﬁle for a Snap-In, where extension_name is the name assigned to an extension with the SDK Extension Wizard. The extension_name_Validate() function conﬁrms that the data passed into an extension through its arguments is valid.

3-32 SDK for Snap-Ins Programmer’s Manual CMetaObject

CMetaObject

CObject

CCmdTarget

COlapObject

CMetaObject

The CMetaObject class functions as an abstract base class for many other MetaCube classes but cannot be instantiated itself. The CMetaObject class provides many of the common characteristics of the objects that are its children. You can call CMetaObject member functions for any objects descended from a CMetaObject object. All of the object classes that deﬁne a metamodel, such as Attributes, Dimen- sions, DimensionElement, and FactTable, are children of the CMetaObject class. Of the object classes accessible through the SDK programming interface, the CMetaObject class serves as a parent for the following:

■ Metabase ■ Filter ■ FilterElement

MetaCube Class Library 3-33 CMetaObject Class Members

CMetaObject Class Members

Operations

GetDirty Determines if an object’s deﬁnition that is stored in metadata has changed since the object was last saved

GetVeriﬁed Retrieves the veriﬁcation results returned by Verify() without calling that member function again

GetVerifyResults Retrieves a pointer to the ValueList object created by calling the Verify() function. That ValueList object contains any messages generated during the veriﬁcation process.

Verify Reviews the validity of the metadata deﬁnitions represented by an object and any other objects within that object’s collections and sub-collections

3-34 SDK for Snap-Ins Programmer’s Manual CMetaObject::GetDirty

CMetaObject::GetDirty

BOOL GetDirty();

Return Value

A Boolean value. Nonzero indicates an object has changed since it was last saved. Zero indicates the object is unchanged.

Remarks

Call this member function to determine if the deﬁnition of an object that is stored in metadata has changed since the object was last saved.

MetaCube Class Library 3-35 CMetaObject::GetVeriﬁed

CMetaObject::GetVeriﬁed

long GetVerified()

Return Value

A integer that shows the veriﬁcation results returned the last time Verify() was called.

Remarks

Call this member function to retrieve the verifications results returned by Verify() without calling that member function again. Verify() reviews the validity of the metadata definitions represented by an object and any other objects within that object’s collections and sub-collections. The metacons.h file defines possible verification results and assigns a constant to each. The following table duplicates the verification results listed in metacons.h:

Filter Element Type Name in Metacons.h Constant

Object has never been veriﬁed VeriﬁedNever 0

Object veriﬁed successfully VeriﬁedGood 1

Object itself veriﬁes, but other VeriﬁedBadBelow 2 objects in its collections or sub-collections do not

Object itself fails to verify VeriﬁedBad 3

3-36 SDK for Snap-Ins Programmer’s Manual CMetaObject::GetVerifyResults

CMetaObject::GetVerifyResults

LPDISPATCH GetVerifyResults();

Return Value

An IDispatch pointer to a ValueList object that was created when Verify() was called.

Remarks

Call this member function to retrieve a pointer to a ValueList object created by calling the Verify() function. This ValueList object contains any messages generated while the Verify() function checked the validity of the metadata deﬁnitions represented by an object and any other objects within that object’s collections and sub-collections.

MetaCube Class Library 3-37 CMetaObject::Verify

CMetaObject::Verify

long Verify()

Return Value

A integer that represents veriﬁcation results.

Remarks

Call this member function to review the validity of the metadata definitions represented by an object and any other objects within that object’s collections and sub-collections. The metacons.h file defines possible verification results and assigns a constant to each. The following table duplicates the verification results listed in metacons.h:

Filter Element Type Name in Metacons.h Constant

Object has never been veriﬁed VeriﬁedNever 0

Object veriﬁed successfully VeriﬁedGood 1

Object itself veriﬁes, but other VeriﬁedBadBelow 2 objects in its collections or sub-collections do not

Object itself fails to verify VeriﬁedBad 3

3-38 SDK for Snap-Ins Programmer’s Manual COlapException

COlapException

CObject

CException

COlapException

A COlapException object is constructed and thrown when a MetaCube operation encounters an error. For a handler catching a COlapException object, two member functions can be used to determine what type of error has been caught.

COlapException Class Members

Operations

Get_m_code Retrieves the code for the error that caused this COlapException object to be thrown

Get_m_reason Returns an alphanumeric string describing the error that caused this COlapException object to be thrown

MetaCube Class Library 3-39 COlapException::Get_m_code

COlapException::Get_m_code

WORD& Get_m_code();

Return Value

A reference to a WORD containing the error code for this COlapException object.

Remarks

Call this member function to retrieve the code for the error that caused this COlapException object to be thrown. The error.h ﬁle lists constants for all the possible OLAP errors.

COlapException::Get_m_reason

CString& Get_m_reason()

Return Value

A reference to a CString containing text describing an exception.

Remarks

Call this member function to retrieve an alphanumeric string describing the error that caused this COlapException object to be thrown. The MetaCube engine generates an appropriate text string for each error.

3-40 SDK for Snap-Ins Programmer’s Manual COlapObject

COlapObject

CObject

CCmdTarget

COlapObject

The COlapObject class functions as an abstract base class for all other MetaCube classes but cannot be instantiated itself. The COlapObject class provides characteristics that are common to all MetaCube objects. You can call COlapObject member functions for any MetaCube object.

COlapObject Class Members

Operations

Get_m_application Returns a reference to a pointer identifying the application, the MetaCube engine

Get_m_iparent Retrieves a reference to a pointer to the parent object for this object

Get_m_metabase Retrieves the Metabase object

GetApplication Returns a pointer identifying the application, the MetaCube engine

GetParent Retrieves an IDispatch pointer to the parent object for this object

GetRefCount Retrieves the OLE reference count associated with the object

GetType Returns a string identifying the class to which an object belongs

MetaCube Class Library 3-41 COlapObject::Get_m_application

COlapObject::Get_m_application

LPDISPATCH& Get_m_application();

Return Value

A reference to an IDispatch pointer that identiﬁes the MetaCube engine.

Remarks

Call this member function to identify the application, the MetaCube engine.

COlapObject::Get_m_iparent

class COlapObject*& Get_m_iparent()

Return Value

A reference to a pointer to the parent object for this object.

Remarks

Use this member function to retrieve a reference to a pointer to the parent object for this object.

3-42 SDK for Snap-Ins Programmer’s Manual COlapObject::Get_m_metabase

COlapObject::Get_m_metabase

class Metabase*& Get_m_metabase()

Return Value

A reference to a pointer to the Metabase object that is the master object for this object.

Remarks

Call this member function to retrieve the Metabase object. For every MetaCube procedure, a Metabase object is the master object, with all other objects existing as children, grandchildren, great-grandchildren, and so forth of this master object.

COlapObject::GetApplication

LPDISPATCH GetApplication();

Return Value

An IDispatch pointer that identiﬁes the MetaCube engine.

Remarks

Call this member function to identify the application, the MetaCube engine.

MetaCube Class Library 3-43 COlapObject::GetParent

COlapObject::GetParent

LPDISPATCH GetParent()

Return Value

An IDispatch pointer that identiﬁes the parent object for this object.

Remarks

Call this member function to retrieve an IDispatch pointer to the parent object for this object.

COlapObject::GetRefCount

long GetRefCount()

Return Value

A long integer that is the OLE reference count.

Remarks

Call this member function to retrieve the OLE reference count associated with an object. This is a read-only function that is typically used for debugging purposes.

3-44 SDK for Snap-Ins Programmer’s Manual COlapObject::GetType

COlapObject::GetType

BSTR GetType();

Return Value

An OLE string that provides the name of the class to which an object belongs.

Remarks

Call this member function to identify the class to which an object belongs. For example, if an object belongs to the Filter class, the string that is returned contains “Filter”.

MetaCube Class Library 3-45 COleCollection

COleCollection

CObject

CCmdTarget

COlapObject

COleCollection

The COleCollection class functions as an abstract base class for all the collection classes of MetaCube objects but cannot be instantiated itself. The COleCollection class provides characteristics that are common to all collections. You can call COleCollection member functions to modify any of the MetaCube collections.

3-46 SDK for Snap-Ins Programmer’s Manual COleCollection Class Members

COleCollection Class Members

Operations

AddItem Adds an object to a collection and puts the object at the end of the collection

Get_m_count Determines how many objects a collection holds and returns a reference to a long integer

GetCount Determines how many objects a collection holds and returns a long integer

GetElementIndex Retrieves a number identifying an object’s position within a collection

GetItem Retrieves an IDispatch pointer to an object in a collection

GetNames Retrieves an IDispatch pointer to a ValueList object containing the names of objects in a collection

IGetItem Retrieves a pointer to an object in the collection

IMakeNth Rearranges a collection of objects so the speciﬁed object takes a designated position in the collection

IRemoveAll Removes all objects from a collection

MakeFirst Rearranges the order of objects in a collection so the speciﬁed object becomes the ﬁrst item

MakeLast Rearranges the order of objects in a collection so the speciﬁed object becomes the last item

MakeNth Rearranges a collection of objects so the speciﬁed object takes a designated position in the collection

Remove A virtual function that cannot be called. The presence of this virtual function requires all the derived collection classes to include a Remove() function.

MetaCube Class Library 3-47 COleCollection Class Members

Operations

RemoveItem Removes an object from the collection of objects. The object to be removed can be speciﬁed by a number or a constant that can be either a name or a number.

RemoveAll Removes all objects from a collection and calls the OLE release function

Swap Swaps the position of two objects in a collection of objects

3-48 SDK for Snap-Ins Programmer’s Manual COleCollection::AddItem

COleCollection::AddItem

void AddItem( LPDISPATCH element );

Parameters index An IDispatch pointer to the object being added to a collection.

Remarks

Call this member function to add an object to a collection and put the object at the end of the collection.

COleCollection::Get_m_count

long& Get_m_count()

Return Value

A reference to a long integer representing the number of objects in a collection.

Remarks

Call this member function to determine how many objects a collection holds.

MetaCube Class Library 3-49 COleCollection::GetCount

COleCollection::GetCount

long GetCount();

Return Value

A long integer representing the number of objects in a collection.

Remarks

Call this member function to determine how many objects a collection holds.

COleCollection::GetElementIndex

long GetElementIndex( LPDISPATCH element )

Return Value

A long integer identifying an object’s position in a collection.

Parameters

element The IDispatch pointer to an object.

Remarks

Call this member function to retrieve a number identifying an object’s position within a collection.

3-50 SDK for Snap-Ins Programmer’s Manual COleCollection::GetItem

COleCollection::GetItem

LPDISPATCH GetItem( const VARIANT FAR& index )

Return Value

An IDispatch pointer to an object in a collection.

Parameters index A constant representing the object to be retrieved. The index constant can be a long integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to retrieve an IDispatch pointer to an object in a collection.

COleCollection::GetNames

LPDISPATCH GetNames()

Return Value

The IDispatch pointer associated with a ValueList object containing object names.

Remarks

Call this member function to retrieve a pointer to a ValueList object containing the names of the objects in a collection.

MetaCube Class Library 3-51 COleCollection::IGetItem

COleCollection::IGetItem

class COlapObject* IGetItem( const VARIANT FAR& index ); class COlapObject* IGetItem( long index ); class COlapObject* IGetItem( CString& index );

Return Value

A pointer to a MetaCube object derived from the COlapObject class.

Parameters

index The index representing the object to be retrieved. The index can be speciﬁed with any of the following: ■ A constant representing the object. The index constant can be a long integer (the 0-based index of the object) or a string (the name of the object). ■ The 0-based index of the object ■ A reference to a CString object containing a name

Remarks

Call this member function to retrieve a pointer to a MetaCube object derived from the COlapObject class. Three versions of this member function exist. All produce the same result but allow you to use different methods to identify the object to be retrieved.

3-52 SDK for Snap-Ins Programmer’s Manual COleCollection::IMakeNth

COleCollection::IMakeNth

void IMakeNth( long index, long n );

Parameters index The 0-based index of the object to be moved n A number specifying the new position for the object to be moved

Remarks

Call this member function to rearrange a collection of objects so the speciﬁed object takes a designated position in the collection.

COleCollection::IRemoveAll

void IRemoveAll();

Remarks

Call this member function to remove all objects from a collection.

MetaCube Class Library 3-53 COleCollection::MakeFirst

COleCollection::MakeFirst

void MakeFirst( const VARIANT FAR& index );

Parameters

index A constant representing the object to be moved within the collection of objects. The index constant can be an integer (the 0- based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of objects in a collection so a speciﬁed object becomes the ﬁrst item.

COleCollection::MakeLast

void MakeLast( const VARIANT FAR& index );

Parameters

index A constant representing the object to be moved within the collection of objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of objects in a collection so a speciﬁed object becomes the last item.

3-54 SDK for Snap-Ins Programmer’s Manual COleCollection::MakeNth

COleCollection::MakeNth

void MakeNth( const VARIANT FAR& index, long n );

Parameters index A constant representing the object to be moved within the collection of objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object). n A number specifying the new position for the object to be moved

Remarks

Call this member function to rearrange a collection of objects so the speciﬁed object takes a designated position in the collection.

COleCollection::Remove

virtual void Remove( const VARIANT FAR& index ) = 0;

Parameters index A constant representing the object to be removed. The index constant can be a long integer (the 0-based index of the object) or a string (the name of the object).

Remarks

This member function is a virtual function, which requires that a Remove() function be implemented for all the derived MetaCube collection classes.

MetaCube Class Library 3-55 COleCollection::RemoveAll

COleCollection::RemoveAll

void RemoveAll( BOOL release = FALSE );

Parameters

release An optional argument requiring a Boolean value. If set to TRUE, all objects are removed from a collection and destroyed. If set to FALSE, all object are removed from a collection but they are not destroyed. If not supplied, the argument defaults to FALSE.

Remarks

When this member function is called and its argument is set to TRUE, the function removes all objects from a collection and calls the OLE release function to destroy those object. When the argument is set to FALSE, the function removes all objects from a collection without destroying them.

3-56 SDK for Snap-Ins Programmer’s Manual COleCollection::RemoveItem

COleCollection::RemoveItem

LPDISPATCH RemoveItem( const VARIANT FAR& index ); LPDISPATCH RemoveItem( long index );

Return Value

An IDispatch pointer to the object being removed from the collection.

Parameters index The index representing the object to be removed. The index can be speciﬁed with any of the following: ■ A constant representing the object. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object). ■ The 0-based index of the object

Remarks

Call this member function to remove an object from the collection of objects. Two versions of this member function exist. Both produce the same result, but they allow you to identify the object to be removed by different methods. Unlike the Remove() member function in most of the MetaCube collection classes, this member function returns a handle to the object being removed.

MetaCube Class Library 3-57 COleCollection::Swap

COleCollection::Swap

void Swap( const VARIANT FAR& index1, const VARIANT FAR& index2 );

Parameters

index1 A constant representing the object whose position will be swapped within the collection of objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

index2 A constant representing the other object to be swapped. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to swap the position of two objects in a collection of objects.

3-58 SDK for Snap-Ins Programmer’s Manual CParseNode

CParseNode

CObject

CParseNode

Every CParseNode object provides pieces of information about an extension call. Using parent/child relationships, CParseNode objects form hierarchical tree structures, with each object representing a node in the tree. A tree of CParseNode objects collectively provides all the information necessary to process or validate an extension. MetaCube generates all CParseNode objects, and they should require no additional modiﬁcation. For each CParseNode object, data members provide the following pieces of information:

■ Type: The m_type data member deﬁnes an object as one of the following: ❑ NameType: CParseNode object has a string value and no children ❑ NumberType: CParseNode object has a number value and no children ❑ TupleType: CParseNode object has two children but no string or number value ❑ FunctionType: CParseNode object has a string value that contains a function call and a child object representing each of the arguments needed for that function call ■ Children: The m_type data member contains pointers to any CParseNode objects that are the children of this object. ■ Value: The m_string_val or the m_number_val data members deﬁne a value that is a string or a number (except for TupleType objects, which have no value).

MetaCube Class Library 3-59 CParseNode

The highest level CParseNode object in a tree essentially holds all the information necessary to process an extension. Figure 18 shows the CParseNode object tree needed to parse the syntax for a complex function call that ranks, in ascending order, the moving average of three measure values. In this case, the measure is Units Sold. The syntax for this function is shown below:

RANK(MOVINGAVG(Measures.Sales Transactions.Units Sold, 3), ASC)

Figure 18 CParseNode Object Tree for a Complex Function Call

m_type = FunctionType The highest level CParseNode object is a FunctionType. It has a string value that contains the function call ‘RANK’, which m_string_val = ‘RANK’ requires two arguments.

Both CParseNode objects on this level represent arguments for the RANK() function. One argument is a string m_type = FunctionType m_type = NameType containing the function call ‘MOVINGAVG’. m_string_val = ‘MOVINGAVG’ m_string_val = ‘ASC’ The other argument speciﬁes the sorting order (ASC, for ascending) for RANK.

Both CParseNode objects on m_type = NameType m_type = NumberType this level represent arguments for the MOVINGAVG() function. m_string_val = ‘Measures.Sales Transactions.Units Sold’ m_number_val = 3 One argument identiﬁes the Measure being averaged. The other argument speciﬁes the number of values to be averaged for that measure.

When an extension is processed or validated, a handle to the top-level CParseNode object is used to access all the information needed for the extension. Internally, MetaCube also uses nodes on the CParseNode tree to process and validate functions that may be nested within an extension.

3-60 SDK for Snap-Ins Programmer’s Manual CParseNode Class Members

CParseNode Class Members

Data Members m_children Deﬁnes a pointer to an array of CParseNode objects that are the children of this CParseNode object m_number_val Provides a number that is the value for this CParseNode object m_state Used by QueryCategory extensions, which are not supported in this version of the SDK programming interface m_string_val Provides a string that is the value for this CParseNode object m_type Identiﬁes the CParseNode object as an enumerated type

MetaCube Class Library 3-61 CParseNode::m_children

CParseNode::m_children

CArray m_children;

Remarks

This data member deﬁnes a pointer to an array of CParseNode objects that are the children of this CParseNode object. Through the use of these pointers, CParseNode objects form a tree holding all the information needed to process or validate the syntax of an extension.

CParseNode::m_number_val

double m_number_val;

Remarks

This data member provides a double that is the value for this CParseNode object.

CParseNode::m_state

void* m_state;

Remarks

This data member is used by QueryCategory extensions, which are not supported in this version of the SDK programming interface.

3-62 SDK for Snap-Ins Programmer’s Manual CParseNode::m_string_val

CParseNode::m_string_val

CString m_string_val;

Remarks

This data member provides a string that is the value for this CParseNode object.

CParseNode::m_type

enum { NameType, NumberType, TupleType FunctionType, UnsetType } m_type;

Remarks

This data member identiﬁes the CParseNode object as an enumerated type. The object’s type determines what value the object has (if any), and it determines whether the object is the parent of other CParseNode objects. The following types are possible:

NameType Must have a value that is a string, and it can have no children objects

NumberType Must have a value that is a number, and it can have no children objects

TupleType Must have two children objects but cannot have a string or number value

FunctionType Must have a value that is a string that contains the name of a function. The children of this CParseNode object provide the arguments to the function. Because every extension must have at least one argument, all FunctionType objects must have at least one child object.

Unset Indicates the type of this object has not been set.

MetaCube Class Library 3-63 CPlugIn

CPlugIn

CObject

CPlugIn

A CPlugIn object describes a Snap-In (that is, an .mcx file) to the MetaCube engine. For every .mcx file, a CPlugIn object should exist. The SDK Extension Wizard generates a PlugIn.h file that contains all the code needed for a CPlugIn object, and that code requires no modification. Note that the PlugIn.h file includes a constant called MCXSDK_VERSION. This constant is used to identify versions of the SDK. The MetaCube engine uses this version information to load extension files correctly.

CPlugIn Class Members

Operations

m_dll Deﬁnes a handle to the Windows DLL ﬁle implementing a Snap- In

m_extensions Provides a pointer to an array of CIExtension objects associated with this .mcx ﬁle

m_metabase Provides a pointer to the Metabase object

3-64 SDK for Snap-Ins Programmer’s Manual CPlugIn::m_dll

CPlugIn::m_dll

HINSTANCE m_dll;

Remarks

This data member defines a handle to the Windows DLL (dynamic-link library) file implementing this Snap-In. MetaCube Snap-In files, which use the .mcx file name extension, are a specific type of DLL file.

CPlugIn::m_extensions

CArray m_extensions;

Remarks

This data member provides a pointer to an array of CIExtension objects. An .mcx file, which constitutes a Snap-In, can include multiple extensions. Each extension is represented by a CIExtension object. The array identified by the m_extensions data member lists the CIExtension objects associated with this .mcx file.

CPlugIn::m_metabase

class Metabase* m_metabase;

Remarks

This data member provides a pointer to the Metabase object.

MetaCube Class Library 3-65 CQueryCube

CQueryCube

CObject

CQueryCube

A QueryCube is a hypercube of data that has been pivoted into rows, columns, and pages. It holds the results of a query. An extension can perform its calculations and changes on a QueryCube and the data it holds. The CQueryCube member functions allow you to obtain information about the QueryCube and its contents. You can retrieve the values of cells and labeling information associated with each row, column, and page. You can change the value of a cell. Member functions can be used for retrieving QueryCube data, or they can be used to manipulate the cells in a QueryCube. The CQueryCube member functions also allow you to add and delete rows, columns, and pages.

3-66 SDK for Snap-Ins Programmer’s Manual CQueryCube Class Members

CQueryCube Class Members

Operations

DeleteCell; Deletes a cell in the QueryCube

DeleteColumn; Deletes a column in the QueryCube

DeletePage; Deletes a page in the QueryCube

DeleteRow; Deletes a row in the QueryCube

Get_m_cellcount; Determines how many cells the QueryCube contains

Get_m_dimcount; Determines how many dimensions the QueryCube contains

Get_m_dimonly; Determines if a query reports only dimension information and does not report any measure data

Get_m_iparent; Identiﬁes the Query object that is the parent of this object

Get_m_numpages; Determines how many pages the QueryCube contains

GetCell; Points a reference to a structure that contains the value for a speciﬁed cell

GetCellItemIndex; Points a reference to an index identifying the QueryItem reported in a cell

GetCellKey; Points a reference to a CKeyArray, which provides all the dimension keys applicable to this cell

GetColDimIndexes; Points a reference to an array that contains indexes to the QueryCategory objects that return values arranged in a column orientation

GetColDims; Points a reference to an array of the names of the QueryCat- egory objects that return values arranged in a column orientation

GetColLabels; Points a reference to an array containing the column for the speciﬁed column

GetDimCounts; Points references to integers indicating how many Query- Category object return values arranged in page, row, or column orientations

MetaCube Class Library 3-67 CQueryCube Class Members

Operations

GetPageDimIndexes; Points a reference to an array that contains indexes to the QueryCategory objects that return values arranged in a page orientation

GetPageDims; Points a reference to an array of the names of the QueryCat- egory objects that return values arranged in a page orientation

GetPageLabels; Points a reference to an array containing the labels for the speciﬁed page

GetPageSize; Points references to integers indicating the number of rows and columns on a speciﬁed page in the QueryCube

GetRowDimIndexes; Points a reference to an array that contains indexes to the QueryCategory objects that return values arranged in a row orientation

GetRowDims; Points a reference to an array of the names of the QueryCat- egory objects that return values arranged in row orientation

GetRowLabels; Points a reference to an array containing the labels for the speciﬁed row

InsertColumn; Inserts a column into a QueryCube

InsertPage; Inserts a page into a QueryCube

InsertRow; Inserts a row into a QueryCube

SetCell; Sets the value of a cell in a QueryCube

3-68 SDK for Snap-Ins Programmer’s Manual CQueryCube::DeleteCell

CQueryCube::DeleteCell

void DeleteCell( long page_num, long rownum, long colnum );

Parameters page_num A long integer specifying the page containing the cell to be deleted rownum A long integer specifying the row containing the cell to be deleted colnum A long integer specifying the column containing the cell to be deleted

Remarks

Call this member function to delete a cell. A hole is left in the QueryCube when a cell is deleted, and the hole can remain unﬁlled.

CQueryCube::DeleteColumn

void DeleteColumn( long page_num, long colnum );

Parameters page_num A long integer specifying the page containing the column to be deleted colnum A long integer specifying the column to be deleted

Remarks

Call this member function to delete a column in a QueryCube.

MetaCube Class Library 3-69 CQueryCube::DeletePage

CQueryCube::DeletePage

void DeletePage( long page_num );

Parameters

page_num A long integer specifying the page to be deleted

Remarks

Call this member function to delete a page in a QueryCube.

CQueryCube::DeleteRow

void DeleteRow( long page_num, long rownum );

Parameters

page_num A long integer specifying the page containing the row to be deleted

rownum A long integer specifying the row to be deleted

Remarks

Call this member function to delete a row in a QueryCube.

3-70 SDK for Snap-Ins Programmer’s Manual CQueryCube::Get_m_cellcount

CQueryCube::Get_m_cellcount

long& Get_m_cellcount();

Return Value

A reference to a long integer indicating the number of cells in a QueryCube.

Remarks

Call this member function to determine how many cells the QueryCube contains.

CQueryCube::Get_m_dimcount

long& Get_m_dimcount();

Return Value

A reference to a long integer indicating the number of dimensions in a QueryCube.

Remarks

Call this member function to determine how many dimensions the QueryCube contains. For example, if a query groups data by brand and by region, the QueryCube for that query has two dimensions. If the query groups data by brand only, the QueryCube has one dimension.

MetaCube Class Library 3-71 CQueryCube::Get_m_dimonly

CQueryCube::Get_m_dimonly

BOOL& Get_m_dimonly();

Return Value

A reference to a Boolean value. Nonzero indicates the query is a dimension- only query. Zero indicates the query reports measure data as well as information about a dimension.

Remarks

Call this member function to determine if a query reports dimension information only and does not report any measure data. At this time, an extension developed with the SDK Extension Wizard cannot be invoked on a dimension-only QueryCube because the SDK supports QueryItem extensions only, and QueryItem extensions must act on measure data.

CQueryCube::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A reference to the Query object that is the parent of this object.

Remarks

Use this member function to identify the Query object that is the parent of this object.

3-72 SDK for Snap-Ins Programmer’s Manual CQueryCube::Get_m_numpages

CQueryCube::Get_m_numpages

long& Get_m_numpages();

Return Value

A reference to a long integer indicating the number of pages in a QueryCube.

Remarks

Call this member function to determine how many pages the QueryCube contains.

MetaCube Class Library 3-73 CQueryCube::GetCell

CQueryCube::GetCell

void GetCell( long page_num, long rownum, long colnum, SCell*& cell );

Parameters

page_num The number of the page containing the cell whose value will be referenced

rownum The number of the row containing the cell whose value will be referenced

colnum The number of the column containing the cell whose value will be referenced

cell A reference that returns a pointer to an SCell structure, which holds the value for the speciﬁed cell. If the speciﬁed cell does not exist, a null pointer is referenced.

Remarks

Call this member function to point a reference to an SCell structure that contains the value for a specified cell. The sdk.h file defines the SCell structure. Do not modify the values in a SCell structure referenced by this member function. Instead, use SetCell() to change those values. For convenience, the members of an SCell structure are listed and defined below.

cell_value A double containing the value of the cell

cell_format A CString containing the syntax used for formatting numeric data in different display environments. Typically cell formatting is supplied by MetaCube Warehouse Manager, but QueryItem::SetFormatString() can be used to control the format of cells for a particular QueryItem.

cell_item_index An index into the QueryItem collection associated with this query

cell_error A double containing the error value for a cell if sampling is used for this query

3-74 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetCell

Example

CQueryCube* qcube = query->Get_m_qcube();

BOOL column_orientation = FALSE; if (query->Get_m_itemOrientation() == OrientationColumn) column_orientation = TRUE; . . . SCell* cell_val = NULLP(SCell);

// Get the cell...

if (column_orientation) qcube->GetCell(page, position, location, cell_val); else qcube->GetCell(page, location, position, cell_val);

MetaCube Class Library 3-75 CQueryCube::GetCellItemIndex

CQueryCube::GetCellItemIndex

void GetCellItemIndex( long page_num, long rownum, long colnum, long& index );

Parameters

page_num The number of the page containing the cell for which a QueryItem is referenced

rownum The number of the row containing the cell for which a QueryItem is referenced

colnum The number of the column containing the cell for which a QueryItem is referenced

index A reference that returns a long integer that is the index to the QueryItem reported in this cell

Remarks

Call this member function to point a reference to an index that identiﬁes the QueryItem reported in a cell. Multiple cells can report data for the same set of QueryCategory values—such as Alden (for brand), West (for region), and January (for month)—but only one QueryItem value, such as value for Units Sold or Gross Revenue, can be reported in that cell. GetCellItemIndex() references the index to the QueryItem that is associated with a particular cell. The Process function in the template code generated by the SDK Extension Wizard calls GetCellItemIndex() to determine if the cell’s value applies to this function, as shown in the following example.

3-76 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetCellItemIndex

Example

CQueryCube* qcube = query->Get_m_qcube();

BOOL column_orientation = FALSE; if (query->Get_m_itemOrientation() == OrientationColumn) column_orientation = TRUE; . . . for (long location = 0; location < max_dist; ++location) { // Now, walk and look for our row/column...

long cell_index;

if (column_orientation) qcube->GetCellItemIndex(page, 0, location, cell_index); else qcube->GetCellItemIndex(page, location, 0, cell_index);

// Is it me?

if (cell_index == item_index) { . . . }

MetaCube Class Library 3-77 CQueryCube::GetCellKey

CQueryCube::GetCellKey

void GetCellKey( long page_num, long rownum, long colnum, CKeyArray& key );

Parameters

page_num The number of the page containing the cell whose dimension keys will be referenced

rownum The number of the row containing the cell whose dimension keys will be referenced

colnum The number of the column containing the cell whose dimension keys will be referenced

key A reference that returns a CKeyArray, which provides the dimension keys applicable to this cell. The sdk.h ﬁle deﬁnes a CKeyArray as a type of CArray containing CDimKey objects.

Remarks

Call this member function to point a reference to a CKeyArray that provides all the dimension keys applicable to this cell. For example, consider a query that reports units sold by brand (oriented by row), region (oriented by column), and month (oriented by page). A CKeyArray retrieved for a cell in that QueryCube would contain three dimension keys. A typical set of dimension keys would be Alden (for brand), West (for region), and January (for month). GetCellKey() is useful for comparing one cell to another.

3-78 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetColDimIndexes

CQueryCube::GetColDimIndexes

void GetColDimIndexes( CLongArray& dims );

Parameters dims A reference that returns a CLongArray, which contains indexes to the QueryCategory objects arranged in a column orientation. The sdk.h ﬁle deﬁnes a CLongArray as a type of CArray containing longs.

Remarks

Call this member function to point a reference to an array containing indexes to the QueryCategory objects that return values arranged in column orientation. A query contains a collection of QueryCategory objects and each returns values that can be arranged in a row, column, or page orientation. For example, if a QueryCube contains values for a collection of six QueryCat- egory objects, and the second and fourth of those QueryCategory objects use a column orientation, GetColDimIndexes() would reference an array that consists of the 0-based integers 1 and 3.

MetaCube Class Library 3-79 CQueryCube::GetColDims

CQueryCube::GetColDims

void GetColDims( CStringArray& dimlabels );

Parameters

dimlabels A reference that returns a CStringArray, which contains the names of the QueryCategory objects arranged in a column orientation

Remarks

Call this member function to point a reference to an array of the names of the QueryCategory objects that return values arranged in a column orientation. For example, if two QueryCategory objects, Brand and Region, return values in a column orientation, this member function would reference an array that contains two strings: ‘Brand’ and ‘Region’.

3-80 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetColLabels

CQueryCube::GetColLabels

void GetColLabels( long page_num, long colnum, CStringArray& labels );

Parameters page_num The number of the page containing the column whose labels will be retrieved colnum The number of the column whose labels will be retrieved labels A reference that returns a CStringArray, which contains the labels for the speciﬁed column

Remarks

Call this member function to point a reference to an array that contains the labels for a speciﬁed column. For example, if a QueryCube contains columns that list units sold by both company and brand, a column might have a label for a company called Electrotron and a second label for a brand called Alden. When GetColLabels() is called for that column, it will reference a CStrin- gArray that contains the strings ‘Electrotron’ and ‘Alden’. GetColLabels() is most useful for outputting column information. To manipulate cells or to compare one cell to another, use the member function GetCellKey().

MetaCube Class Library 3-81 CQueryCube::GetDimCounts

CQueryCube::GetDimCounts

void GetDimCounts( long& page_dims, long& row_dims, long& col_dims );

Parameters

page_dims A reference that returns a long integer indicating the number of QueryCategory objects arranged by page

row_dims A reference that returns a long integer indicating the number of QueryCategory objects arranged by row

col_dims A reference that returns a long integer indicating the number of QueryCategory objects arranged by column

Remarks

Call this member function to point references to integers that indicate how many QueryCategory objects return values in page, row, or column orientation. For example, if a query has a collection of three QueryCategory objects, such as brand, region, and month, this member function determines how many of those return values arranged by row, how many by column, and how many by page.

Example

CQueryCube* qcube = query->Get_m_qcube(); . . . long page_dims; long row_dims; long col_dims;

qcube->GetDimCounts(page_dims, row_dims, col_dims);

3-82 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetPageDimIndexes

CQueryCube::GetPageDimIndexes

void GetPageDimIndexes( CLongArray& dims );

Parameters dims A reference that returns a CLongArray, which contains indexes to the QueryCategory objects arranged in a page orientation. The sdk.h ﬁle deﬁnes a CLongArray as a type of CArray containing longs.

Remarks

Call this member function to point a reference to an array containing indexes to the QueryCategory objects that return values arranged in a page orientation. A query contains a collection of QueryCategory objects and each returns values that can be arranged in a row, column, or page orientation. For example, if a QueryCube contains values for a collection of six QueryCat- egory objects, and the second and fourth of those QueryCategory objects use a page orientation, GetPageDimIndexes() would reference an array that consists of the 0-based integers 1 and 3.

MetaCube Class Library 3-83 CQueryCube::GetPageDims

CQueryCube::GetPageDims

void GetPageDims( CStringArray& dimlabels );

Parameters

dimlabels A reference that returns a CStringArray, which contains the names of the QueryCategory objects arranged in a page orientation

Remarks

Call this member function to point a reference to an array of the names of the QueryCategory objects that return values arranged in a page orientation. For example, if two QueryCategory objects, Brand and Region, return values in a page orientation, this member function would reference an array that contains two strings: ‘Brand’ and ‘Region’.

3-84 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetPageLabels

CQueryCube::GetPageLabels

void GetPageLabels( long page_num, CStringArray& labels );

Parameters page_num The number of the page whose labels will be retrieved labels A reference that returns a CStringArray, which contains the labels for the speciﬁed page.

Remarks

Call this member function to point a reference to an array that contains the labels for a speciﬁed page. For example, if a QueryCube contains pages that list units sold by both company and month, a page might have a label for a company called Electrotron and a second label for the month January. When GetPageLabels() is called for that page, it will reference a CStringArray that contains the strings ‘Electrotron’ and ‘January’. GetPageLabels() is most useful for outputting page information. To manipulate cells or to compare one cell to another, use the member function GetCellKey().

MetaCube Class Library 3-85 CQueryCube::GetPageSize

CQueryCube::GetPageSize

void GetPageSize( long page_num, long& rows, long& columns );

Parameters

page_num A long integer specifying the page whose size you want to know

rows A reference that returns a long integer, which indicates the number of rows on the page speciﬁed with page_num

columns A reference that returns a long integer, which indicates the number of columns on the page speciﬁed with page_num

Remarks

Call this member function to point references to integers indicating the number of rows and columns on a particular page in the QueryCube.

Example

CQueryCube* qcube = query->Get_m_qcube(); . . . for (long page = 0; page < qcube->Get_m_numpages(); ++page) { // Get the bounds... long rows; long columns;

qcube->GetPageSize(page, rows, columns);

long max_dist;

if (column_orientation) max_dist = columns; else max_dist = rows; . . . }

3-86 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetRowDimIndexes

CQueryCube::GetRowDimIndexes

void GetRowDimIndexes( CLongArray& dims );

Parameters dims A reference that returns a CLongArray, which contains indexes to the QueryCategory objects arranged in a row orientation. The sdk.h ﬁle deﬁnes a CLongArray as a type of CArray containing longs.

Remarks

Call this member function to point a reference to an array containing indexes to the QueryCategory objects that return values arranged in a row orientation. A query contains a collection of QueryCategory objects and each returns values that can be arranged in a row, column, or page orientation. For example, if a QueryCube contains values for a collection of six QueryCat- egory objects, and the second and fourth of those QueryCategory objects use a row orientation, GetRowDimIndexes() would reference an array that consists of the 0-based integers 1 and 3.

MetaCube Class Library 3-87 CQueryCube::GetRowDims

CQueryCube::GetRowDims

void GetRowDims( CStringArray& dimlabels );

Parameters

dimlabels A reference that returns a CStringArray, which contains the names of the QueryCategory objects arranged in a row orientation

Remarks

Call this member function to point a reference to an array of the names of the QueryCategory objects that return values arranged in a row orientation. For example, if two QueryCategories, Brand and Region, return values in a row orientation, this member function would reference an array that contains two strings: ‘Brand’ and ‘Region’.

3-88 SDK for Snap-Ins Programmer’s Manual CQueryCube::GetRowLabels

CQueryCube::GetRowLabels

void GetRowLabels( long page_num, long rownum, CStringArray& labels );

Parameters page_num The number of the page containing the row whose labels will be retrieved rownum The number of the row whose labels will be retrieved labels A reference that returns a CStringArray, which contains the labels for the speciﬁed row

Remarks

Call this member function to point a reference to an array that contains the labels for a speciﬁed row. For example, if a QueryCube contains rows that list units sold by both company and brand, one row might have a label for a company called Electrotron and a second label for a brand called Alden. When GetRowLabels() is called for that row, it will reference a CStringArray that contains the strings ‘Electrotron’ and ‘Alden’. GetRowLabels() is most useful for outputting row information. To manipulate cells or to compare one cell to another, use the member function GetCellKey().

MetaCube Class Library 3-89 CQueryCube::InsertColumn

CQueryCube::InsertColumn

void InsertColumn( long page_num, long colnum, CKeyArray& keys );

Parameters

page_num The number of the page where a column will be inserted

colnum The number of the column to be inserted

keys A reference to a CKeyArray that will provide the dimension keys for the column being inserted. The sdk.h ﬁle deﬁnes a CKeyArray as a type of CArray containing CDimKey objects.

Remarks

Call this member function to insert a column into a QueryCube. To specify a column you must identify the page where the column will be inserted, the number of the column to insert, and an array of CDimKey objects that will provide the dimension keys for the new column. For example, if a QueryCube contains columns that list units sold by company and by a particular brand, and you are inserting a new row, the CKeyArray must include two dimension keys, one providing the name of the company and one providing the brand name.

3-90 SDK for Snap-Ins Programmer’s Manual CQueryCube::InsertPage

CQueryCube::InsertPage

void InsertPage( long page_num, CKeyArray& keys );

Parameters page_num The number of the page to be inserted keys A reference to a CKeyArray that will provide the dimension keys for the page being inserted. The sdk.h ﬁle deﬁnes a CKeyArray as a type of CArray containing CDimKey objects.

Remarks

Call this member function to insert a page into a QueryCube. To specify a row you must identify the page to be inserted and an array of CDimKey objects that will provide the dimension keys for the new page. For example, if a QueryCube contains pages that list units sold by company and by a month, and you are inserting a new page, the CKeyArray must include two dimension keys, one providing the name of the company and one providing the month.

MetaCube Class Library 3-91 CQueryCube::InsertRow

CQueryCube::InsertRow

void InsertRow( long page_num, long rownum, CKeyArray& keys );

Parameters

page_num The number of the page where a row will be inserted

rownum The number of the row to be inserted

keys A reference to a CKeyArray that will provide the dimension keys for the row being inserted. The sdk.h ﬁle deﬁnes a CKeyArray as a type of CArray containing CDimKey objects.

Remarks

Call this member function to insert a row into a QueryCube. To specify a row you must identify the page where the row will be inserted, the number of the row to insert, and an array of CDimKey objects that will provide the dimension keys for the new row. For example, if a QueryCube contains rows that list units sold by company and brand, and you are inserting a new row, the CKeyArray must include two dimension keys, one providing the name of the company and one providing the brand name.

3-92 SDK for Snap-Ins Programmer’s Manual CQueryCube::SetCell

CQueryCube::SetCell

void SetCell( long page_num, long rownum, long colnum, SCell& cell );

Parameters page_num The number of the page containing the cell whose value will be set rownum The number of the row containing the cell whose value will be set colnum The number of the column containing the cell whose value will be set cell A reference to the SCell structure to be used to assign a value to the speciﬁed cell

Remarks

Call this member function to set the value of a cell in a QueryCube. The value assigned to a cell is an SCell structure. The sdk.h file defines SCell structures. For convenience, the members of an SCell structure are also listed and defined below: cell_value A double containing the value of the cell cell_format A CString containing the syntax used for formatting numeric data in different display environments. Typically cell formatting is supplied by MetaCube Warehouse Manager, but QueryItem::SetFormatString() can be used to control the format of cells for a particular QueryItem. cell_item_index An index into the QueryItem collection associated with this query cell_error A double containing the error value for a cell if sampling is used for this query

MetaCube Class Library 3-93 CQueryCube::SetCell

Example

CQueryCube* qcube = query->Get_m_qcube();

BOOL column_orientation = FALSE; if (query->Get_m_itemOrientation() == OrientationColumn) column_orientation = TRUE; . . . // Store the values...

new_value.cell_value = new_val; new_value.cell_error = new_error;

// Put it in the cube...

if (column_orientation) qcube->SetCell(page, position, location, new_value); else qcube->SetCell(page, location, position, new_value);

3-94 SDK for Snap-Ins Programmer’s Manual CSelect

CSelect

CObject

CSelect

Objects of the CSelect class embody a connection to an SQL SELECT statement. The CDb::SelectStmt member function creates a CSelect object. While the CSelect object exists, you can extract data from it using the CSelect member functions. When the CSelect object is no longer needed, you can destroy it using the CDb::EndSelect member function.

CSelect Class Members

Operations

Deﬁne Deﬁnes the return buffers and format for the data contained in a CSelect object

Fetch Retrieves the data whose output buffers and format were deﬁned by calling Deﬁne()

RowCount Determines the number of rows retrieved so far by calling Fetch()

MetaCube Class Library 3-95 CSelect::Deﬁne

CSelect::Deﬁne

void Define( long ndefines, long* types, void** bufs, long* sizes, long** nulls = NULLP(long*) );

Parameters

ndeﬁnes The number of columns of data contained in a CSelect object.

types A pointer to a long integer or an array of constants specifying the data type for an argument. The cdb.h ﬁle deﬁnes a name and constant for each of the possible data types. They are:

Name Constant Data Type

DB_CHAR 1 char* DB_NUM 2 long DB_FLOAT 3 ﬂoat DB_DOUBLE 4 double

bufs An array of pointers to the buffers that will receive information

sizes An array of pointers defining the sizes of each buffer used to receive information. A maximum length must be defined for each buffer. This size defines the maximum length of a column.

nulls An optional array of pointers to buffers with null values to be set. MetaCube sets a value of null or not null for each of the buffers. The cdb.h file defines a name and constant for each of the null flags. They are:

Name Constant Description

DB_NULL -1 SQL_NULL_DATA DB_NNULL -3 SQL_NTS

Remarks

Call this member function to deﬁne the return buffers and format for the data contained in a CSelect object. After Deﬁne() has been called, call Fetch() to retrieve the data.

3-96 SDK for Snap-Ins Programmer’s Manual CSelect::Fetch

CSelect::Fetch

long Fetch();

Return Value

A long integer that shows the number of rows returned.

Remarks

Call this member function to retrieve the data whose output buffers and format were deﬁned by calling Deﬁne().

CSelect::RowCount

long RowCount();

Return Value

A long integer that shows the number of rows retrieved.

Remarks

Call this member function to determine the number of rows retrieved so far by calling Fetch().

MetaCube Class Library 3-97 Extension

Extension

CObject

CCmdTarget

COlapObject

Extension

The Extension class of objects allows you to incorporate the functionality of extensions into MetaCube. Each Extension object represents a Snap-In (that is, an .mcx file) that can contain one or more utilities, such as a harmonic moving average. After a .cpp file has been compiled in C++ and the resulting .mcx file has been snapped into MetaCube, the extension can be registered using Explorer or another tool to append an entry to MetaCube’s initialization file, metacube.ini. This entry, called EnabledExtensions, identifies the file name and path of the extension and appears under the [Engine] header. When an application calls the MetaCube engine, the engine automatically enables the extensions identified in the initialization file. Do not confuse a CIExtension object with an Extension object. A CIExtension object represents a utility contained within a Snap-In, such as a harmonic moving average. A Snap-In may contain multiple utilities.

3-98 SDK for Snap-Ins Programmer’s Manual Extension Class Members

Extension Class Members

Operations

GetArguments Retrieves a ValueList object containing the arguments needed for each function included in an extension

GetArgumentTypes Retrieves a ValueList object containing the argument types needed for each function included in an extension

GetDescription Retrieves a string containing a description of an extension

GetFileName Retrieves a string containing the ﬁle name of the compiled extension code

GetFunctions Retrieves a ValueList object containing the functions included in an extension

GetTypes Retrieves a ValueList object that contains the object class to which a function applies

OnEnabledChanged Issues a notiﬁcation that the value of m_enabled has changed.

OnFinalRelease An OLE function that de-registers an object so it can be destroyed

RefreshList An OLE function called to ﬁll a ValueList

Data Members m_dll A handle to a Windows DLL (dynamic-link library) file implementing an extension m_enabled A Boolean value indicating whether an extension has been identified in the metacube.ini file m_fileName A string containing the file name of the compiled extension code m_ifunctions A ValueList object that contains the functions included in an extension m_itypes A ValueList object that contains the object class to which a function applies

MetaCube Class Library 3-99 Extension Class Members

Data Members

m_iarguments A ValueList object that stores the arguments needed for each function included in an extension

m_iargumenttypes A ValueList object that stores the argument types needed for each function included in an extension

m_plugin A CPlugin object, which encapsulates the lists of all the extensions in a ﬁle

3-100 SDK for Snap-Ins Programmer’s Manual Extension::GetArguments

Extension::GetArguments

LPDISPATCH GetArguments( LPCTSTR Function );

Return Value

The IDispatch pointer associated with the ValueList object containing the descriptions of arguments for the speciﬁed function.

Parameters

Function A text string providing the name of the function for which arguments are being retrieved.

Remarks

Call this member function to retrieve descriptions of the arguments needed for each function included in an extension. Arguments are stored in a ValueList object in the order in which they must be speciﬁed.

MetaCube Class Library 3-101 Extension::GetArgumentTypes

Extension::GetArgumentTypes

LPDISPATCH GetArgumentTypes( LPCTSTR Function );

Return Value

The IDispatch pointer associated with the ValueList object containing the descriptions of the types of arguments for a speciﬁed function.

Parameters

Function A text string providing the name of the function for which argument types are being retrieved.

Remarks

Call this member function to retrieve a description of the type of each argument needed for each function included an extension. Argument types are stored in a ValueList object in the same order as their corresponding arguments.

Extension::GetDescription

BSTR GetDescription();

Return Value

An OLE string containing a description of an extension.

Remarks

Call this member function to retrieve a description of an extension.

3-102 SDK for Snap-Ins Programmer’s Manual Extension::GetFileName

Extension::GetFileName

BSTR GetFileName();

Return Value

An OLE string containing the ﬁle name of the compiled extension code.

Remarks

Call this member function to retrieve a string containing the ﬁle name of the compiled extension code.

Extension::GetFunctions

LPDISPATCH GetFunctions();

Return Value

The IDispatch pointer associated with a ValueList object.

Remarks

Call this member function to retrieve a ValueList object that contains the names of the functions included in an extension.

MetaCube Class Library 3-103 Extension::GetTypes

Extension::GetTypes

LPDISPATCH GetTypes();

Return Value

The IDispatch pointer associated with a ValueList object.

Remarks

Call this member function to retrieve a ValueList object that contains descriptions of the object classes to which functions apply, typically either QueryCategory or QueryItem.

Extension::m_dll

HINSTANCE m_dll;

Remarks

This data member defines a handle to a Windows DLL (dynamic-link library) file implementing a Snap-In. MetaCube Snap-In files, which use the.mcx file name extension, are a specific type of DLL file.

3-104 SDK for Snap-Ins Programmer’s Manual Extension::m_enabled

Extension::m_enabled

BOOL m_enabled;

Remarks

This data member stores a Boolean value. Nonzero indicates the extension has been enabled. Zero indicates the extension has not been enabled. Extensions are enabled in the metacube.ini file. Under the [Engine] section of the file, entries read “EnabledExtensions=” and “DisabledExtensions=”. To enable one or more extensions, enter the full path to the .mcx file containing the extension, as in the following example:

EnabledExtensions=C:\MetaCube\MCPlgMN.mcx,C:\MetaCube\harmonics.mcx When you change the value of m_enabled, you should call OnEnabledChanged().

Extension::m_ﬁleName

CString m_fileName;

Remarks

This data member is a string containing the ﬁle name of the compiled extension code.

MetaCube Class Library 3-105 Extension::m_iarguments

Extension::m_iarguments

ValueList m_iarguments;

Remarks

This data member is a ValueList object that stores the arguments needed for each function included in an extension. The user should never set any of the values stored with this data member

Extension::m_iargumenttypes

ValueList m_iargumenttypes;

Remarks

This data member is a ValueList object that indicates the type of each argument needed for each function included an extension. The argument types are stored in the same order as their corresponding arguments.

Extension::m_ifunctions

ValueList m_ifunctions;

Remarks

This data member is a ValueList object that contains the functions included in an extension.

3-106 SDK for Snap-Ins Programmer’s Manual Extension::m_itypes

Extension::m_itypes

ValueList m_itypes;

Remarks

This data member is a ValueList object that contains the object class to which a function applies, typically either QueryCategory or QueryItem.

Extension::m_plugin

class CPlugIn* m_plugin;

Remarks

This data member is a pointer to a CPlugIn object, which encapsulates a Snap-In (that is, an .mcx ﬁle) for the MetaCube engine.

Extension::OnEnabledChanged

void OnEnabledChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value stored by m_enabled has changed.

MetaCube Class Library 3-107 Extension::RefreshList

Extension::RefreshList

void RefreshList( class ValueList* list);

Parameters

list A pointer to the ValueList object that is being ﬁlled.

Remarks

When a function returns a ValueList object, this OLE function is called to ﬁll the ValueList. The user should never call this member function.

Extension::OnFinalRelease

virtual void OnFinalRelease();

Remarks

OLE uses the OnFinalRelease() function to perform clean-up before destroying an object. The user should never call this member function.

3-108 SDK for Snap-Ins Programmer’s Manual Extensions

Extensions

CObject

CCmdTarget

COlapObject

COleCollection

Extensions

The Extensions class of objects manage collections of Extension objects. The Extensions member functions allow you to add new Extension objects to a collection and remove Extension objects from the collection. Adding a new Extension object makes that extension available for all subsequent connections between an application and the MetaCube engine. Removing the Extension object disables an extension.

Extensions Class Members

Operations

Add Creates a new Extension object, which makes that extension available for all subsequent connections between an application and the MetaCube engine

OnFinalRelease An OLE function that de-registers an object so it can be destroyed

Remove Removes an Extension object from a collection of Extension objects

MetaCube Class Library 3-109 Extensions::Add

Extensions::Add

LPDISPATCH Add( LPCTSTR FileName );

Return Value

The IDispatch pointer associated with the Extension object being created.

Parameters

FileName Pointer to the text string that provides the file name of the extension to be added. The file name should include the full path to the file.

Remarks

Call this member function to create a new Extension object, which adds the new Extension object to a collection of Extension objects and returns a pointer to the new object. Calling this member function also registers the new extension in MetaCube’s initialization ﬁle, which makes the extension available in all subsequent connections between an application and the MetaCube engine.

Extensions::OnFinalRelease

virtual void OnFinalRelease();

Remarks

OLE uses the OnFinalRelease() function to perform clean-up before destroying an object. The user should never call this member function.

3-110 SDK for Snap-Ins Programmer’s Manual Extensions::Remove

Extensions::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the Extension object to be removed from the collection of Extension objects. The constant is an integer (the 0-based index of the object).

Remarks

Call this member function to remove an Extension object from a collection of Extension objects.

MetaCube Class Library 3-111 Filter

Filter

CObject

CCmdTarget

COlapObject

CMetaObject

Filter

MetaCube filters limit the range of data retrieved by a query or incorporated into an aggregate table. The Filter class of objects provides a programming interface for MetaCube functionality related to MetaCube filters. All MetaCube functionality related to filters can be represented using the Filter class of objects or the Filters class of object. “Filters” on page 132, describes how collections of Filter objects are created and associated with other objects.

3-112 SDK for Snap-Ins Programmer’s Manual Filter Class Members

Filter Class Members

Operations

DeleteFilter Deletes the metadata storing a ﬁlter’s deﬁnition, regardless of whether a Filter object exists within a collection of Filter objects

GetFilterElements Retrieves a pointer to the FilterElements object that is contained within a Filter object

GetFolder Retrieves a pointer to the Folder object that contains a Filter object

Get_m_enabled Prevents MetaCube from applying a ﬁlter to a query result

Get_m_group Identiﬁes the name of the dimension or fact table by which a ﬁlter is grouped

Get_m_iparent Identiﬁes the object that contains a collection of Filter objects

GetName Retrieves the name of a Filter object

GetOwner Retrieves the name of the user who owns a Filter object

GetSaved Determines whether the deﬁnition of a ﬁlter has been changed since it was last saved

GetUpdatable Determines whether the current user has privileges to change the deﬁnition of a ﬁlter

OnEnabledChanged Call this member function to issue a notiﬁcation that the value returned by Get_m_enabled() has changed

OnGroupChanged Call this member function to issue a notiﬁcation that the value returned by Get_m_group() has changed

Save Saves the deﬁnition of a ﬁlter

SaveAs Saves a new Filter object, saves an existing Filter object under a new name, or saves an existing Filter object to a different Folder object

SetName Changes the name of a ﬁlter

MetaCube Class Library 3-113 Filter::DeleteFilter

Filter::DeleteFilter

void DeleteFilter();

Remarks

Call this member function to delete the metadata in a relational database that stores a ﬁlter’s deﬁnition regardless of whether the Filter object exists in a collection of Filter objects.

Filter::Get_m_enabled

BOOL& Get_m_enabled();

Return Value

A reference to a Boolean value. Zero precludes MetaCube from applying a ﬁlter to a query result without excluding that Filter from a collection of Filter objects owned by a Query object. Nonzero does not preclude MetaCube from applying a ﬁlter to a query result.

Remarks

Call this member function to prevent MetaCube from applying a ﬁlter to a query result. When you change the value returned by this function, you should call OnEnabledChanged().

3-114 SDK for Snap-Ins Programmer’s Manual Filter::Get_m_group

Filter::Get_m_group

CString& Get_m_group();

Return Value

A reference to the name of the group with which a ﬁlter is associated.

Remarks

Call this member function to retrieve the name of the group, such as a dimension or fact table, with which a filter is associated. When you change the value returned by this function, you should call OnGroupChanged(). For MetaCube Explorer and MetaCube for Excel, the string returned by Get_m_group() is used to associate filters with dimensions. For a filter based on an attribute, the string is the name of the Dimension object, such as Geography. For a filter based on a measure, the string is Measures.Fact(‘Table Name’), such as Measures.Fact(‘Units Sold’). To ensure compatibility with MetaCube Explorer and MetaCube for Excel, you should use Get_m_group() to implement those conventions, but that technique is not mandatory.

Filter::Get_m_iparent

class COlapObject*& Get_m_iparent();

Return Value

A reference to the object that is the parent of a collection of Filter objects.

Remarks

Use this member function to identify the object that is the parent of a collection of Filter objects.

MetaCube Class Library 3-115 Filter::GetFilterElements

Filter::GetFilterElements

LPDISPATCH GetFilterElements();

Return Value

The IDispatch pointer associated with a FilterElements object.

Remarks

Call this member function to retrieve the pointer to a collection of Filter- Element objects contained by the Filter object. Each of the FilterElement objects in the collection provides criteria for the ﬁlter.

Filter::GetFolder

LPDISPATCH GetFolder();

Return Value

The IDispatch pointer associated with the Folder object that contains a Filter object. If this member function is called on an unsaved ﬁlter, null is returned.

Remarks

Call this member function to retrieve the pointer to a Folder object that contains a Filter object. A Filter object is always contained within a Folder object if the Filter object has been saved.

3-116 SDK for Snap-Ins Programmer’s Manual Filter::GetName

Filter::GetName

BSTR GetName();

Return Value

An OLE string containing the name of the Filter object.

Remarks

Call this member function to retrieve the existing name of a Filter object.

Filter::GetOwner

BSTR GetOwner();

Return Value

An OLE string containing the name of the user who owns the Filter object.

Remarks

Call this member function to retrieve the name of user who owns a Filter object. The default owner is the login ID of the user who created the ﬁlter.

MetaCube Class Library 3-117 Filter::GetSaved

Filter::GetSaved

BOOL GetSaved();

Return Value

A Boolean value. Nonzero indicates the filter has not changed since it was last saved; zero indicates the definition of the filter has changed or has never been saved.

Remarks

Call this member function to determine whether the deﬁnition of a ﬁlter has changed.

Filter::GetUpdatable

BOOL GetUpdatable();

Return Value

A Boolean value. Nonzero indicates the current user has privileges to change the filter’s definition; zero indicates the current user does not have privileges to change the filter’s definition.

Remarks

Call this member function to determine whether the current user has privileges to change a filter’s definition. In this release, the return value is always nonzero; the current user always has privileges to change a filter’s definition.

3-118 SDK for Snap-Ins Programmer’s Manual Filter::OnEnabledChanged

Filter::OnEnabledChanged

void OnEnabledChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_enabled() has changed.

Filter::OnGroupChanged

void OnGroupChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_group() has changed.

Filter::Save

void Save();

Remarks

Call this member function to save the definition of an existing filter in metadata tables on the relational database. The filter is saved under its current name, folder, owner, and group. To change any of these values, call Folder::RenameFilter. To create a copy of a filter with a new name, folder, or group, call Filter::SaveAs. The first time a filter is saved, you must call SaveAs(), because the values for the filter have not been set.

MetaCube Class Library 3-119 Filter::SaveAs

Filter::SaveAs

void SaveAs( LPCTSTR Name, LPDISPATCH aFolder );

Parameters

Name Speciﬁes the new name of the ﬁlter

aFolder Provides the IDispatch pointer associated with the Folder object containing this Filter object

Remarks

Call this member function to save a new Filter object, save an existing Filter object under a new name, or assign an existing Filter object to a different Folder object. Before calling this function, Get_m_group() should be called to specify the dimension or fact table with which a ﬁlter is grouped.

Filter::SetName

void SetName( LPCTSTR lpszNewValue );

Parameters

lpszNewValue Points to the text string providing a new name for the ﬁlter

Remarks

Call this member function to change the name of a Filter object.

3-120 SDK for Snap-Ins Programmer’s Manual FilterElement

FilterElement

CObject

CCmdTarget

COlapObject

CMetaObject

FilterElement

MetaCube filters limit the range of data retrieved by a query or incorporated into an aggregate table. Each of the individual criteria defining a filter is specified using a FilterElement object, which identifies values within a measure, attribute, or dimension element to include or exclude from reports. A Filter object contains a collection of FilterElement objects. Together those FilterElement objects define the characteristics of the Filter. “FilterElements” on page 128 describes how collections of FilterElement objects are created and associated with other objects.

MetaCube Class Library 3-121 FilterElement Class Members

FilterElement Class Members

Operations

Get_m_iparent Identiﬁes the object that contains a FilterElement object

Get_m_operand Retrieves the names of the values within an attribute, dimension element, or measure that a FilterElement object includes or excludes

Get_m_operator Retrieves the operator that a FilterElement object uses

GetFilterOn Retrieves the name of the attribute, dimension element, or measure on which a FilterElement operates

GetFilterType Retrieves a long integer value corresponding to the type of object (Attribute, DimensionElement, or Measure) on which a FilterElement operates

GetObject Retrieves a pointer to the Attribute, DimensionElement, or Measure object on which a FilterElement object operates

OnOperandChanged Issues a notiﬁcation that the value returned by Get_m_operand() has changed

OnOperatorChanged Issues a notiﬁcation that the value returned by Get_m_operator() has changed

SetFilterOn Changes the attribute, dimension element, or measure on which a FilterElement object operates

3-122 SDK for Snap-Ins Programmer’s Manual FilterElement::Get_m_iparent

FilterElement::Get_m_iparent

class Filter*& Get_m_iparent();

Remarks

Use this member function to identify the Filter object that contains a Filter- Element object.

FilterElement::Get_m_operand

CString& Get_m_operand();

Return Value

A reference to a CString containing the values within the attribute, dimension element, or measure that a FilterElement object includes or excludes from a report.

Remarks

Call this member function to retrieve a reference to a CString containing the values within the attribute, dimension element, or measure that a Filter- Element object includes or excludes from a report. An example of an operand string is "'Alden'" or "3". When you change the value returned by this function, you should call OnOperandChanged(). Note that the programmer is responsible for ensuring that the operand belongs in a syntactically correct SQL statement. An operand string is placed directly into the SQL. MetaCube does not check syntax or do any processing of the operand string. One exception to this rule is user-deﬁned or time- dependent parameters, which must be enclosed in double brackets ("<<" and ">>"). For more information on user-deﬁned or time-dependent parameters, see “FilterElements::Add” on page 3-129.

MetaCube Class Library 3-123 FilterElement::Get_m_operator

FilterElement::Get_m_operator

CString& Get_m_operator();

Return Value

A reference to a CString containing the operator that a FilterElement object uses.

Remarks

Call this member function to retrieve a reference to a CString containing the operator that a FilterElement object uses. An example of an operator string is “>”. When you change the value returned by this function, you should call OnOperatorChanged(). Note that the operator is placed directly into the SQL. MetaCube does not check syntax or do any processing. The programmer is responsible for ensuring that the operator belongs in a syntactically correct SQL statement.

FilterElement::GetFilterOn

BSTR GetFilterOn();

Return Value

The OLE string containing the name of the attribute, dimension element, or measure on which a FilterElement object operates.

Remarks

Call this member function to retrieve the name of the attribute, dimension element, or measure on which a FilterElement object operates. The name that is retrieved is the name that was passed in as a parameter when the Filter- Element object was created using FilterElements::Add() function.

3-124 SDK for Snap-Ins Programmer’s Manual FilterElement::GetFilterType

FilterElement::GetFilterType

long GetFilterType();

Return Value

A long integer that shows the type of MetaCube object on which a FilterElement object operates.

Remarks

Call this member function to retrieve the type of MetaCube object on which a FilterElement object operates. The metacons.h file defines filter element types and assigns a constant to each. The following table duplicates the filter element information listed in metacons.h:

Filter Element Type Name in Metacons.h Constant

Other FilterTypeOther 0

Attribute FilterTypeStandard 1

Dimension Element FilterTypeDimensionElement 2

Measure FilterTypeMeasure 3

MetaCube Class Library 3-125 FilterElement::GetObject

FilterElement::GetObject

LPDISPATCH GetObject();

Return Value

The IDispatch pointer associated with the Attribute, DimensionElement, or Measure object on which a FilterElement object operates.

Remarks

Call this member function to retrieve the Attribute, DimensionElement, or Measure object on which a FilterElement object operates.

FilterElement::OnOperandChanged

void OnOperandChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_operand() has changed.

FilterElement::OnOperatorChanged

void OnOperatorChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_operator() has changed.

3-126 SDK for Snap-Ins Programmer’s Manual FilterElement::SetFilterOn

FilterElement::SetFilterOn

void SetFilterOn( LPCTSTR lpszNewValue );

Parameters lpszNewValue Speciﬁes a new attribute, dimension element, or measure from which values are to be selected

Remarks

Call this member function to change the name of the Attribute, Dimension- Element, or Measure object on which a FilterElement object operates. To avoid ambiguity when specifying the name of an object, follow the appropriate scoping rules, as described in the MetaCube Version 3.0 Technical Reference Manual.

MetaCube Class Library 3-127 FilterElements

FilterElements

CObject

CCmdTarget

COlapObject

COleCollection

FilterElements

The FilterElements class of objects manages collections of FilterElement objects. With this class of objects, FilterElement objects can be created and a parent object can be identiﬁed for a collection of FilterElement objects. The various FilterElement objects in a collection deﬁne the characteristics of a Filter.

FilterElements Class Members

Operations

Add Creates a new FilterElement object

Get_m_iparent Identiﬁes the Filter object that contains a FilterElements object

Remove Removes a FilterElement object from a collection of Filter- Element objects

3-128 SDK for Snap-Ins Programmer’s Manual FilterElements::Add

FilterElements::Add

LPDISPATCH Add( LPCTSTR FilterOn, LPCTSTR Operator, LPCTSTR Operand );

Return Value

The IDispatch pointer associated with the FilterElement object being created.

Parameters

s FilterOn Points to the text string that is the name of the attribute, dimension element, or measure on which the new FilterElement object operates

Operator Points to the text string specifying the operator that the new Filter- Element object uses. The typical operators are =, <, >, <=, >=, in, not in, like, not like, is null, is not null. When specifying an operator, note the following: ■ The “less than” and “greater than” operators can apply to an alphabetic value. “Less than” yields values earlier in the alphabetic sequence; “greater than” yields values later in the alphabetic sequence. The “less than” and “greater than” operators cannot apply to a list of values. ■ The “in” operator allows you to include one or more explicitly identiﬁed values in a FilterElement object, such as the “East” and “West” regions. When using the “in” operator, enclose operand values in parentheses and separate them with commas. ■ The “like” operator allows you to specify a set of letters or digits.

MetaCube Class Library 3-129 FilterElements::Add

Operand Points to the text string specifying the values within the attribute, dimension element, or measure that the new FilterElement object includes or excludes. Time Dependent Filters Because MetaCube can recognize the date of the most recent transaction, you can define dynamic, time-dependent filters that can include different values depending on which values in the Data Warehouse are most recent. The duration of the period reported corresponds to the type of time attribute or dimension element on which you are filtering, such as Day, Week, Month, or Quarter. To create a dynamic time-dependent filter, use one of the following parameters: ■ Current Period ■ Last N Periods (where N can be any integer) ■ Current Period and Same Period Last Year ■ Same Period Last Year When specifying a parameter for a time-dependent filter, enclose the parameter in double brackets, such as <> or <>. Note that MetaCube can understand the + and - functions in time- dependent filters. For example, <> yields the period three periods ago. User-Defined Parameters You can create new parameters that prompt users to enter values immediately prior to the execution of a query. Any value can be assigned to these parameters as long as it is enclosed in double brackets, such as <>. The string enclosed by double brackets is displayed to the end user.

Remarks

Call this member function to create a new FilterElement object, which adds the FilterElement object to a collection of FilterElement objects. Refer to the Informix Guide to SQL Syntax for complete discussion of operator and operand syntax. Note that MetaCube does not check SQL syntax. The programmer is responsible for ensuring that the new ﬁlter element is a syntactically correct SQL statement.

3-130 SDK for Snap-Ins Programmer’s Manual FilterElements::Get_m_iparent

FilterElements::Get_m_iparent

class Filter*& Get_m_iparent;

Return Value

A pointer to the Filter object that contains a collection of FilterElement objects.

Remarks

Use this member function to identify the Filter object that contains a collection of FilterElement objects.

FilterElements::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the FilterElement object to be removed from the collection of FilterElement objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a FilterElement object from a collection of FilterElement objects.

MetaCube Class Library 3-131 Filters

Filters

CObject

CCmdTarget

COlapObject

COleCollection

Filters

The Filters class of objects manages collections of Filter objects. With this class of objects, Filter objects can be created and retrieved. A Filters object also identiﬁes the parent object to which the ﬁlters are applied.

Filters Class Members

Operations

AddDefault Creates a new Filter object using the default ﬁlter deﬁnition for a particular group

AddNewFilter Creates a new Filter object

AddSaved Creates a new Filter object by retrieving a ﬁlter deﬁnition saved to metadata and instantiating it in a new Filter object

Get_m_iparent Identiﬁes the object that contains a collection of Filter objects

GetCountGroup Determines how many Filter objects within the collection are associated with a particular group

GetItemGroup Retrieves a Filter object associated with a particular group

Remove Removes a Filter object from the collection of Filter objects

3-132 SDK for Snap-Ins Programmer’s Manual Filters::AddDefault

Filters::AddDefault

LPDISPATCH AddDefault( LPCTSTR DimensionName );

Return Value

The IDispatch pointer associated with a Filter object being created.

Parameters

DimensionName Points to the text string that is the name of the group that provides a default ﬁlter deﬁnition

Remarks

Call this member function to create a Filter object using the default ﬁlter deﬁnition for a particular group. The new Filter object is added to the collection of Filter objects. You can call this member function only when adding a Filter object to a collection of Filter objects that is contained within a Query object.

MetaCube Class Library 3-133 Filters::AddNewFilter

Filters::AddNewFilter

LPDISPATCH AddNewFilter( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new Filter object.

Parameters

Name Points to the text string that is the name of the new Filter object

Remarks

Call this member function to create a new Filter object. The new Filter object is added to the collection of Filter objects. After creating the new Filter object, you can deﬁne criteria for the ﬁlter by adding FilterElement objects to the collection of FilterElement objects.

3-134 SDK for Snap-Ins Programmer’s Manual Filters::AddSaved

Filters::AddSaved

LPDISPATCH AddSaved( LPCTSTR Name, LPCTSTR Owner, LPDISPATCH aFolder );

Return Value

The IDispatch pointer associated with the Filter object being created.

Parameters

Name Points to the text string that is the name of the Filter object that is being instantiated

Owner Points to the text string that is the name of the user who created the Filter object from which a filter definition is being retrieved. When retrieving a public filter, specify the owner as the string returned by Metabase::GetPublicUser(). aFolder Provides the IDispatch pointer associated with the Folder object that contains the Filter object that is being instantiated.

Remarks

Call this member function to instantiate a Filter object that has been saved in metadata and to add the instantiation to the Filters collection. Through the SDK programming interface, you access any filter definition in the DSS system. Insuring that users access only their own saved filters is the responsibility of the User Interface. MetaCube does not provide security for metadata objects.

MetaCube Class Library 3-135 Filters::Get_m_iparent

Filters::Get_m_iparent

class COlapObject*& Get_m_iparent();

Return Value

A reference to the object that owns a collection of Filter objects.

Remarks

Use this member function to identify the object that owns a collection of Filter objects. For the RootFolder object, this member function returns a reference to the Metabase object.

Filters::GetCountGroup

long GetCountGroup( LPCTSTR Group );

Return Value

A long integer providing the number of Filter objects that are in this collection and in the speciﬁed group.

Parameters

Group Points to the text string that is the name of the group with which Filter objects are associated

Remarks

Call this member function to determine how many Filter objects within a collection are associated with a particular group.

3-136 SDK for Snap-Ins Programmer’s Manual Filters::GetItemGroup

Filters::GetItemGroup

LPDISPATCH GetItemGroup( LPCTSTR Group, long index );

Return Value

The IDispatch pointer for a Filter object that is associated with a particular group and belongs to the collection of Filter objects.

Parameters

Group Points to the text string that is the name of the group with which the Filter object is associated index The 0-based index of the Filter object that is associated with the particular group and belongs to the collection of Filter objects

Remarks

Call this member function to identify, by means of a sequentially generated index number, a Filter object associated with a group.

MetaCube Class Library 3-137 Filters::Remove

Filters::Remove

void Remove( const VARIANT FAR& index );

Parameters

index A constant representing the Filter object to be removed from the collection of Filter objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a Filter object from a collection of Filter objects.

3-138 SDK for Snap-Ins Programmer’s Manual Folder

Folder

CObject

CCmdTarget

COlapObject

Folder

The Folder class of objects provides a programming interface for MetaCube functionality related to MetaCube folders. While the actual definitions of queries and filters remain stored in MetaCube’s metadata tables, the SDK programming interface offers developers a familiar paradigm for organizing that information. MetaCube folders can contain queries and filters, and MetaCube folders can also be contained by other folders. All of this functionality can be represented using the Folder class of objects or the Folders class of objects. “Folders” on page 3-146, describes how collections of Folder objects are created and associated with other Folder objects.

MetaCube Class Library 3-139 Folder Class Members

Folder Class Members

Operations

GetFilterNames Retrieves the names of Filter objects associated with the folder, an owner, and a group

GetFolders Retrieves the pointer to the collection of Folder objects that this Folder object contains

GetFullPathName Retrieves the full path of the Folder object

GetName Retrieves the name of the Folder object

GetQueryNames Retrieves the names of Query objects associated with a folder and an owner

RenameFilter Substitutes a new name, group, and/or owner for a Filter object associated with a Folder object

RenameQuery Substitutes a new name and/or owner for any Query object associated with a Folder object

SetName Sets a new name for a Folder object

3-140 SDK for Snap-Ins Programmer’s Manual Folder::GetFilterNames

Folder::GetFilterNames

LPDISPATCH GetFilterNames( LPCTSTR Owner, LPCTSTR Group );

Return Value

The IDispatch pointer associated with a ValueList object containing ﬁlter names.

Parameters

Owner Points to the string that names an owner. The owner is the login ID of the user who saved the ﬁlter.

Group Points to the string that names a group.

Remarks

Call this member function to retrieve the pointer to the names of ﬁlters associated with a folder, owner, and group. The owner is the login ID of the user who saved the ﬁlter. The current user can be retrieved by calling Metabase::Get_m_login(). The public user can be retrieved by calling Metabase::GetPublicUser().

Example

Metabase* metabase; Folder* folder; LPDispatch listdisp; ValueList* namelist; . . . listdisp = folder->GetFilternames( metabase->GetLogin(), “Time” ); namelist* = ( ValueList* )metabase->ObjFromIDispatch( listdisp );

MetaCube Class Library 3-141 Folder::GetFolders

Folder::GetFolders

LPDISPATCH GetFolders();

Return Value

The IDispatch pointer associated with a Folders object.

Remarks

Call this member function to retrieve a pointer to a Folders object. The returned Folders object represents the collection of folders contained within the Folder object.

Folder::GetFullPathName

BSTR GetFullPathName();

Return Value

An OLE string containing the full path to the Folder object.

Remarks

Call this member function to retrieve the full path to a Folder object.

3-142 SDK for Snap-Ins Programmer’s Manual Folder::GetName

Folder::GetName

BSTR GetName();

Return Value

The OLE string containing the name of a folder.

Remarks

Call this member function to retrieve the existing name of a folder.

Folder::GetQueryNames

LPDISPATCH GetQueryNames( LPCTSTR Owner );

Return Value

The IDispatch pointer associated with a ValueList object containing the names of queries.

Parameters

Owner Points to the string that names the owner of a query. The owner is the login ID of the user who saved the query.

Remarks

Call this member function to retrieve the pointer to the names of queries associated with a folder and an owner. The owner is the login ID of the user who saved the queries. To obtain public queries, specify the public user as the name of the user.

MetaCube Class Library 3-143 Folder::RenameFilter

Folder::RenameFilter

void RenameFilter( LPCTSTR OldOwner, LPCTSTR OldGroup, LPCTSTR OldName, LPCTSTR NewOwner, LPCTSTR NewGroup, LPCTSTR NewName );

Parameters

OldOwner Points to the string identifying the current owner of a ﬁlter. The owner is the login ID of the user who saved the ﬁlter.

OldGroup Points to the string identifying the current group associated with the ﬁlter.

OldName Points to the string providing the current name of the ﬁlter.

NewOwner Points to the string identifying the new owner of the ﬁlter.

NewGroup Points to the string identifying the new group associated with the ﬁlter.

NewName Points to the string providing the new name of the ﬁlter.

Remarks

Call this member function to change the name, group, and/or owner of any Filter object associated with a Folder object.

3-144 SDK for Snap-Ins Programmer’s Manual Folder::RenameQuery

Folder::RenameQuery

void RenameQuery( LPCTSTR OldOwner, LPCTSTR OldName, LPCTSTR NewOwner, LPCTSTR NewName );

Parameters

OldOwner Points to the string identifying the current owner of a query. The owner is the login ID of the user who saved the query.

OldName Points to the string providing the current name of the query.

NewOwner Points to the string identifying the new owner of the query.

NewName Points to the string providing the new name of the query.

Remarks

Call this member function to change the name and/or owner of any Query object associated with a Folder object.

Folder::SetName

void SetName( LPCTSTR lpszNewValue );

Parameters lpszNewValue Points to the text string providing a new name for the folder.

Remarks

Call this member function to change the name of the folder.

MetaCube Class Library 3-145 Folders

Folders

CObject

CCmdTarget

COlapObject

COleCollection

Folders

The Folders class of objects manages collections of Folder objects by assem- bling them hierarchically. A Folder object can belong to a collection of Folder objects and that collection can belong to another Folder object. In this way MetaCube objects can represent hierarchical collections of folders. Although the idea of folders may be familiar to users of most operating systems, as a MetaCube object they differ in three respects from other objects:

■ The RootFolder object contains the ﬁrst collection of Folder objects. The RootFolder object is a Folder object in all respects except that its parent is null. A single RootFolder object belongs to each instance of a Metabase object. ■ The only collection of objects belonging to a Folder object is another collection of Folder objects. Because each Folder object can, in turn, contain a collection of Folder objects, the number of collections is unlimited. ■ The level of a collection of Folder objects varies, with some collections belonging directly to the RootFolder object and other collections removed from the RootFolder object by any number of Folder objects.

3-146 SDK for Snap-Ins Programmer’s Manual Folders Class Members

Folders Class Members

Operations

Add Adds a new Folder object to a collection and returns the IDispatch pointer to that new object

Get_m_iparent Identiﬁes the Folder object that contains a collection of Folder objects

Remove Removes a Folder object from a collection of Folder objects

MetaCube Class Library 3-147 Folders::Add

Folders::Add

LPDISPATCH Add( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new Folder object.

Parameters

Name Points to the text string that is the name of the new Folder object.

Remarks

Call this member function to create a new Folder object, which adds the Folder object to a collection of Folder objects and returns the IDispatch pointer to the new Folder object.

Folders::Get_m_iparent

class Folder*& Get_m_iparent();

Return Value

A pointer to the Folder object that contains a collection of Folder objects.

Remarks

Use this member function to identify the Folder object that contains the Folders collection.

3-148 SDK for Snap-Ins Programmer’s Manual Folders::Remove

Folders::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the Folder object to be removed. The index constant can be an integer (the 0-based index of the folder) or a string (the name of the folder).

Remarks

Call this member function to remove a Folder object from a collection of Folder objects.

MetaCube Class Library 3-149 Metabase

Metabase

CObject

CCmdTarget

COlapObject

CMetaObject

Metabase

Each Metabase object is a logical representation of a virtual multi-dimensional database. The properties of a Metabase object specify the relational database on which a multi-dimensional system is based, the multi-dimensional interface used for accessing that relational database, and the analytical functions available. A Metabase object is the master object for every MetaCube object. All other MetaCube objects exist as children, grandchildren, greatgrandchildren, and so forth of the Metabase object. A Metabase object’s collections encompass the entire range of MetaCube functionality. The Dimensions and FactTables collections represent a DSS System’s metadata. Objects in the FactTables and Dimensions collections lay the foundation for the Data Warehouse to process multi-dimensional queries. Objects in the Filters, Queries, and QueryBackJobs collections actually deﬁne those queries, in the multi-dimensional terms inscribed by objects in the Dimensions and FactTables collections.

3-150 SDK for Snap-Ins Programmer’s Manual Metabase Class Members

Metabase Class Members

Operations

CloseDSSSystem Closes the existing DSS System

Connect Logs into the RDBMS and opens a DSS System

CreateNew Creates a new DSS System

DBLogin Logs into the RDBMS without opening a DSS System

DBLogout Disconnects MetaCube from the RDBMS

DeleteMetamodel Deletes a DSS System from metadata in the RDBMS

DeleteQuery Deletes the deﬁnition of a query, stored as a Query object, from the RDBMS metadata

Disconnect Closes the DSS System and disconnects MetaCube from the RDBMS

DoSQL Executes a non-SELECT SQL statement

Get_m_clientType Identiﬁes the development environment in which the Metabase object has been created

Get_m_conﬁguration Identiﬁes a set of Metabase member functions used for connecting to the RDBMS

Get_m_connectDatabase Identiﬁes the vendor and model of an RDBMS, such as Informix Online

Get_m_connected Indicates whether a Metabase object is connected to an RDBMS

Get_m_connectString Identiﬁes the ODBC data source to which MetaCube is connected or will connect

Get_m_dataSkip Determines whether an Informix RDBMS can skip a dbspace that is unavailable during the course of processing a transaction

Get_m_db Identiﬁes the CDb object that embodies the currently active database connection

MetaCube Class Library 3-151 Metabase Class Members

Operations

Get_m_explain Prompts an Informix RDBMS to record execution information in a server-side ﬁle

Get_m_extensions Retrieves a list of all the registered extensions available to the Metabase object

Get_m_lastUpdate Retrieves the date on which the DSS System’s metadata was last modiﬁed

Get_m_localMetamodelFile Retrieves the name of the ﬁle storing a local cache of metadata

Get_m_login Retrieves the user name passed to the RDBMS during log in

Get_m_maxTotalFetches Determines the number of rows that MetaCube can retrieve before aborting a query

Get_m_metacube_path Identiﬁes the directory where the MetaCube engine is installed

Get_m_name Retrieves the string holding the name of the DSS system to be created or the DSS system currently open

Get_m_optimization Determines the extent to which the optimizer of an Informix RDBMS evaluates possible execution strategies for an SQL query

Get_m_password Retrieves the password submitted to the database server

Get_m_pDQPriority Determines the Parallel Data Query (PDQ) Priority of all queries submitted by MetaCube to the Informix database

Get_m_schema Retrieves the schema for metadata tables

Get_m_suppressDialogs Determines whether the MetaCube status window appears in other applications

GetCurrentTime_ Determines the current date and time, as recorded on the PC’s clock

3-152 SDK for Snap-Ins Programmer’s Manual Metabase Class Members

Operations

GetDimensions Identiﬁes the Dimensions object, which is a collection of all the Dimension objects in the DSS system

GetExtensions Identiﬁes the Extensions object, which is a collection of all available Extension objects

GetFactTables Identiﬁes the FactTables object, which is a collection of all the FactTable objects in the DSS system

GetMetamodelNames Identiﬁes a ValueList object that lists all DSS System names in metadata

GetParent Identiﬁes the application object, which is required by OLE

GetPublicUser Returns the name of the user empowered to save queries and ﬁlters that other users can access

GetQueries Identiﬁes the Queries object, which is a collection of Query objects

GetQueryBackJobs Identiﬁes the QueryBackJobs object, which is a collection of QueryBackJob objects

GetRootFolder Identiﬁes the RootFolder object, the Folder object containing all other folders as children, grandchildren, etc.

GetSchemas Identiﬁes the Schemas object, which is a collection of Schema objects

GetSystemMessages Identiﬁes the SystemMessages object, which is a collection of SystemMessage objects

GetUniqueID Obtains a unique identiﬁcation number, which is typically used in a multi-threading environment to ensure that multiple users do not get issued the same identiﬁcation number.

ObjFromDispatch Maps an IDispatch pointer, received from automation member functions of a class, into the CCmdTarget derived object that implements the interfaces of the IDispatch object

MetaCube Class Library 3-153 Metabase Class Members

Operations

OnClientTypeChanged Issues a notiﬁcation that the value returned by Get_m_clientType() has changed

OnConfigurationChanged Issues a notification that the value returned by Get_m_configuration() has changed

OnConnectDatabaseChanged Issues a notiﬁcation that the value returned by Get_m_connectDatabase() has changed

OnConnectStringChanged Issues a notiﬁcation that the value returned by Get_m_connectString() has changed

OnDataSkipChanged Issues a notiﬁcation that the value returned by Get_m_dataSkip() has changed

OnExplainChanged Issues a notiﬁcation that the value returned by Get_m_explain() has changed

OnLocalMetamodelFileChanged Issues a notiﬁcation that the value returned by Get_m_localMetamodelFile() has changed

OnLoginChanged Issues a notiﬁcation that the value returned by Get_m_login() has changed

OnMetaSchemaChanged Issues a notiﬁcation that the value returned by Get_m_schema() has changed

OnNameChanged Issues a notiﬁcation that the value returned by Get_m_name() has changed

OnOptimizationChanged Issues a notiﬁcation that the value returned by Get_m_optimization() has changed

OnPasswordChanged Issues a notiﬁcation that the value returned by Get_m_password() has changed

OnPDQPriorityChanged Issues a notiﬁcation that the value returned by Get_m_pDQPriority() has changed

OpenQuery Instantiates a Query object saved to the metadata

OpenQueryStorage Returns a pointer to a Query object saved in a structured storage object

3-154 SDK for Snap-Ins Programmer’s Manual Metabase Class Members

Operations

OpenDSSSystem Opens a DSS System, as speciﬁed using the Get_m_name() member function

Save Saves changes in a DSS System to RDBMS metadata

SaveAs Saves a new DSS System to RDBMS metadata

MetaCube Class Library 3-155 Metabase::CloseDSSSystem

Metabase::CloseDSSSystem

void CloseDSSSystem();

Remarks

Call this member function to close the existing DSS System.

Metabase::Connect

void Connect();

Remarks

Call this member function to log into the RDBMS and open a DSS System.

Metabase::CreateNew

void CreateNew();

Remarks

Call this member function to create a new DSS System. The member function Get_m_name() provides the name used for the new DSS System. Although it is not mandatory, you should call Get_m_name() to deﬁne a name for a new DSS System before calling CreateNew(). The user running the extension that includes this member function must be a secure user. In other words, in MetaCube Secure Warehouse, that user must be granted authority to access Secure Warehouse and MetaCube Warehouse Manager.

3-156 SDK for Snap-Ins Programmer’s Manual Metabase::DBLogin

Metabase::DBLogin

void DBLogin();

Remarks

Call this member function to log into the RDBMS without opening a DSS System.

Metabase::DBLogout

void DBLogout();

Remarks

Call this member function to disconnect MetaCube from the RDBMS.

MetaCube Class Library 3-157 Metabase::DeleteMetaModel

Metabase::DeleteMetaModel

void DeleteMetaModel( LPCTSTR DSSSystemName );

Parameters

DSSSystemName Points to the text string that is the name of the DSS System to be deleted.

Remarks

Call this member function to delete a DSS System from metadata in the RDBMS. You cannot delete a DSS System to which you are connected. The user running the extension that includes this member function must be a secure user. In other words, in MetaCube Secure Warehouse, that user must be granted authority to access Secure Warehouse and MetaCube Warehouse Manager.

3-158 SDK for Snap-Ins Programmer’s Manual Metabase::DeleteQuery

Metabase::DeleteQuery

void DeleteQuery( LPCTSTR Name, LPCTSTR Author, LPDISPATCH aFolder );

Parameters

Name Points to the string storing the name of the Query object to be deleted.

Author Points to the text string that is the author of the query to be deleted. When a query deﬁnition is saved, the default value for Author is the name of the database user who logged in. aFolder Provides the IDispatch pointer associated with the Folder that contains the Query object to be deleted.

Remarks

Call this member function to delete the deﬁnition of a query, stored as a Query object, from RDBMS metadata.

Metabase::Disconnect

void Disconnect();

Remarks

Call this member function to close the DSS System and disconnect MetaCube from the RDBMS.

MetaCube Class Library 3-159 Metabase::DoSQL

Metabase::DoSQL

void DoSQL( LPCTSTR SQL );

Parameters

SQL Points to the text string that holds a non-SELECT SQL statement

Remarks

Call this member function to execute any non-SELECT SQL statement.

3-160 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_clientType

Metabase::Get_m_clientType

long& Get_m_clientType();

Return Value

A reference to a long integer that represents the client type.

Remarks

Call this member function to identify the development environment in which the Metabase object has been created. When you change the value returned by this function, you should call OnClientTypeChanged(). The value returned by this member function determines the format in which MetaCube returns strings. The metacons.h ﬁle deﬁnes client types and assigns a constant to each type. The following table duplicates the client type information listed in metacons.h:

Development Environment Name in Metacons.h Constant

Visual Basic ClientTypeVB 1

Visual Basic for Applications ClientTypeExcel 2

C ClientTypeC 3

PowerBuilder ClientTypePB 4

MetaCube Class Library 3-161 Metabase::Get_m_conﬁguration

Metabase::Get_m_conﬁguration

CString& Get_m_configuration();

Return Value

A reference to a string that identiﬁes of a set of parameters stored in MetaCube.ini.

Remarks

Call this member function to identify a configuration, which is equivalent to a set of Metabase parameters used for connecting to the RDBMS. Rather than calling each member function individually, you can change the value returned by Get_m_configuration(). That string makes a call to the Metacube.ini file, and within that file, multiple configurations can be stored. The following table lists the MetaCube.ini parameters and their corresponding member functions:

MetaCube.ini Parameter Metabase Member Function

ConnectDatabase Get_m_connectDatabase()

ConnectString Get_m_connectString()

Password Get_m_password()

MetamodelSchema Get_m_schema()

MetamodelFile Get_m_localMetamodelFile()

DSSSystemName Get_m_name()

MaxTotalFetches Get_m_maxTotalFetches()

When you change the value returned by Get_m_conﬁguration(), you should call OnConﬁgurationChanged(). In Version 4.0 and later releases of MetaCube, the MetaCube analysis engine does not use this member function. It is retained, however, for compatibility with earlier releases.

3-162 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_connectDatabase

Metabase::Get_m_connectDatabase

long& Get_m_connectDatabase();

Return Value

A reference to a long integer that represents the vendor of an RDBMS.

Remarks

Call this member function to identify the vendor of an RDBMS. The default value is the vendor defined in the MetaCube.ini file. When you change the value returned by this function, you should call OnConnectDatabase- Changed(). The metacons.h file defines vendors and assigns a constant to each. The following table duplicates the vendor information listed in metacons.h:

Database Vendor Name in Metacons.h Constant

Microsoft Access DBVendorAccess 2

Informix DBVendorInformix 5

MetaCube Class Library 3-163 Metabase::Get_m_connected

Metabase::Get_m_connected

BOOL& Get_m_connected();

Return Value

A reference to a Boolean value. Nonzero indicates the Metabase object has connected to an RDBMS. Zero indicates the connection has not been made.

Remarks

Call this member function to indicate whether a Metabase object has connected to an RDBMS. Note that setting the return value of this member function does not connect you to an RDBMS.

Metabase::Get_m_connectString

CString& Get_m_connectString();

Return Value

A reference to a string that identiﬁes the name of an ODBC data source.

Remarks

Call this member function to identify the name of an ODBC data source. The default value is the ConnectString parameter deﬁned in the MetaCube.ini ﬁle. When you change the value returned by this function, you should call OnConnectStringChanged().

3-164 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_dataSkip

Metabase::Get_m_dataSkip

long& Get_m_dataSkip();

Return Value

A reference to a long integer that determines how an Informix RDBMS responds to unavailable rows when attempting to retrieve data.

Remarks

Call this member function to determine whether an Informix RDBMS can skip a dbspace that is unavailable during the course of processing a transaction. When you change the value returned by this function, you should call OnDataSkipChanged(). The value returned by this member function specifies how an Informix RDBMS responds to unavailable data. The metacons.h file defines constants for the possible types of data skipping functionality. The following table duplicates the data skip constants listed in metacons.h.:

Data Skip Functionality Name in Metacons.h Constant

Abort query if any requested DataSkipOff 0 record is unavailable

Skip any unavailable records, DataSkipOn 1 returning the values that are available

Accept database default for DataSkipDefault 2 Data Skip option

For more information on data skipping, see the SET DATASKIP entry in the Informix Guide to SQL: Syntax.

MetaCube Class Library 3-165 Metabase::Get_m_db

Metabase::Get_m_db

CDb*& Get_m_db();

Return Value

A reference to a CDb object.

Remarks

Call this member function to identify the CDb object that embodies the current actively database connection. Do not set the return value of this function.

Metabase::Get_m_extensions

IExtensionArray& Get_m_extensions();

Return Value

A reference to an array that lists all of the registered extensions available to the Metabase object.

Remarks

Call this member function to retrieve a list of all the registered extensions available to the Metabase object.

3-166 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_explain

Metabase::Get_m_explain

BOOL& Get_m_explain();

Return Value

A reference to a Boolean value. Nonzero prompts an Informix RDBMS to record information generated by the database-server optimizer. Zero, the default value, indicates the Informix database does not record this information.

Remarks

Set the return value of this member function to prompt an Informix RDBMS to record information in a server-side ﬁle named sqexplain.out. This ﬁle records a copy of a query, a plan of execution that the database-server optimizer selects, and an estimate of the amount of work. MetaCube activates this database feature when it connects to an Informix RDBMS. For more information, see the SET EXPLAIN entry in the Informix Guide to SQL: Syntax. When you change the value returned by Get_m_explain() you should call OnExplainChanged().

MetaCube Class Library 3-167 Metabase::Get_m_lastUpdate

Metabase::Get_m_lastUpdate

VARIANT& Get_m_lastUpdate();

Return Value

A reference to a datatype that provides the date on which the DSS System’s metadata was last modiﬁed.

Remarks

Call this member function to retrieve the date on which the DSS System’s metadata was last modiﬁed. Do not set the return value of this function.

Metabase::Get_m_localMetamodelFile

CString& Get_m_localMetamodelFile();

Return Value

A reference to a string that identiﬁes the name of the ﬁle storing a local copy of metadata.

Remarks

Call this member function to retrieve the name of the file storing a local copy of metadata. The default value is the value for the MetamodelFile parameter defined in the MetaCube.ini file. When you change the value returned by Get_m_localMetamodelFile(), you should call OnLocalMetamodelFileChanged().

3-168 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_login

Metabase::Get_m_login

CString& Get_m_login();

Return Value

A reference to a string that identiﬁes the user name passed to the RDBMS during log in.

Remarks

Call this member function to retrieve the user name passed to the RDBMS during log in. The default is the value for the Login parameter deﬁned in the MetaCube.ini ﬁle. When you change the value returned by Get_m_login(), you should call OnLoginChanged().

Metabase::Get_m_maxTotalFetches

long& Get_m_maxTotalFetches();

Return Value

A reference to a long integer that determines the maximum number of rows MetaCube can retrieve before aborting a query.

Remarks

Call this member function to determine the maximum number of rows MetaCube can retrieve before aborting a query.

MetaCube Class Library 3-169 Metabase::Get_m_metacube_path

Metabase::Get_m_metacube_path

CString& Get_m_metacube_path();

Return Value

A reference to a string that identiﬁes the directory where MetaCube is installed.

Remarks

Call this member function to determine the directory where MetaCube is installed. Do not set the string returned by Get_m_metacube_path.

Metabase::Get_m_name

CString& Get_m_name();

Return Value

A reference to a string that identiﬁes the name of a DSS System.

Remarks

Call this member function to retrieve the string holding the name of the DSS System to be created or the DSS System currently open.

3-170 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_optimization

Metabase::Get_m_optimization

BOOL& Get_m_optimization();

Return Value

A reference to a Boolean value. Nonzero, the default value, prompts an Informix RDBMS optimizer to consider every possible execution strategy for an SQL query. Zero prompts the RDBMS to reduce the time spent optimizing SQL queries.

Remarks

Set the return value of this member function to determine the extent to which the optimizer of an Informix RDBMS evaluates possible execution strategies for an SQL query. The optimizer can evaluate every possible execution strategy for an SQL query, or it can be instructed to reduce the time devoted to SQL queries, which may preclude the optimizer from deploying the most efﬁcient execution plan. MetaCube sets the optimization level when it connects to an Informix RDBMS. For more information on optimization, see the SET OPTIMIZATION entry in the Informix Guide to SQL: Syntax. When you change the value returned by Get_m_optimization(), you should call OnOptimizationChanged().

MetaCube Class Library 3-171 Metabase::Get_m_password

Metabase::Get_m_password

CString& Get_m_password();

Return Value

A reference to a string that identiﬁes the password submitted to the database server.

Remarks

Call this member function to retrieve the password submitted to the database server. The default value can be read from the MetaCube.ini file, if the Password parameter has been defined there. When you change the value returned by Get_m_password(), you should call OnPasswordChanged(). Note that setting the password using the SDK programming interface does not automatically record a value in MetaCube’s initialization file. However, MetaCube will read a default password from the initialization file if one appears there.

3-172 SDK for Snap-Ins Programmer’s Manual Metabase::Get_m_pDQPriority

Metabase::Get_m_pDQPriority

long& Get_m_pDQPriority();

Return Value

A reference to a long integer that designates the Parallel Data Query (PDQ) Priority of all decision support queries submitted by MetaCube to the Informix database.

Remarks

Set the return value of this member function to designate the Parallel Data Query (PDQ) Priority of all decision support queries submitted by MetaCube to the Informix database. When you change the value returned by Get_m_pDQPriority(), you should call OnPDQPriorityChanged(). PDQ Priorities determine the extent to which the Informix database executes queries in parallel, as described below:

■ A value of -1, the default, indicates MetaCube will not set PDQ Prior- ities. Instead, the database will use its system default for PDQ PRIOTRITY. Use -1 when connecting to databases that do not support PDQPRIORITY or when submitting queries to a unipro- cessor server. ■ A value of 0 precludes parallel operations. ■ A value of 1 enables only parallel scans. ■ Values between 2 and 100 represent the percent of available system resources that queries can consume. In multiprocessor systems, high PDQ Priorities enable the database to process queries faster. PDQ Priorities may be limited by environment variables and ﬁles established by the database administrator when conﬁguring the Informix RDBMS. MetaCube attempts to set PDQPRIORITY for all queries when it connects to an Informix RDBMS. For more information on PDQ Priority, see the SET PDQPRIORITY entry in the Informix Guide to SQL: Syntax.

MetaCube Class Library 3-173 Metabase::Get_m_schema

Metabase::Get_m_schema

CString& Get_m_schema();

Return Value

A reference to a string that identiﬁes the schema for metadata tables.

Remarks

Call this member function to retrieve the schema for metadata tables. The default is the value for the MetamodelSchema parameter deﬁned in the MetaCube.ini ﬁle. When you change the value returned by Get_m_schema(), you should call OnMetaSchemaChanged().

Metabase::Get_m_suppressDialogs

BOOL& Get_m_suppressDialogs();

Return Value

A reference to a Boolean value. Nonzero prevents the MetaCube status windows from appearing in an application. Zero, the default value, allows MetaCube status windows to appear in an application.

Remarks

Set the return value of this member function to determine whether MetaCube status windows appear in other applications.

3-174 SDK for Snap-Ins Programmer’s Manual Metabase::GetCurrentTime_

Metabase::GetCurrentTime_

VARIANT GetCurrentTime_();

Return Value

A VARIANT that provides the current date and time, as recorded on the PC’s clock.

Remarks

Call this member function to determine the current date and time, as recorded on the PC’s clock.

Metabase::GetDimensions

LPDISPATCH GetDimensions();

Return Value

The IDispatch pointer associated with the Dimensions object, which is a collection of all the Dimension objects in the DSS system.

Remarks

Call this member function to identify the Dimensions object, which is a collection of all the Dimension objects in the DSS system. A Dimension object represents a set of hierarchically related categories for grouping transactional data.

MetaCube Class Library 3-175 Metabase::GetExtensions

Metabase::GetExtensions

LPDISPATCH GetExtensions();

Return Value

The IDispatch pointer associated with the Extensions object, which is a collection of all registered Extension objects.

Remarks

Call this member function to identify the Extensions object, which is a collection of all registered Extension objects. Each Extension object corresponds to a Snap-In (a .mcx ﬁle), which provides one or more functional extensions to MetaCube’s analytical engine.

Metabase::GetFactTables

LPDISPATCH GetFactTables();

Return Value

The IDispatch pointer associated with the FactTables object, which is a collection of all the FactTable objects in the DSS system.

Remarks

Call this member function to identify the FactTables object, which is a collection of all the FactTable objects in the DSS system. A FactTable object describes the location of the fact table containing transaction-level data stored in the Data Warehouse. A FactTable object also describes the dimensions to which the fact table joins, the fact table’s size, the measures it contains, and other information.

3-176 SDK for Snap-Ins Programmer’s Manual Metabase::GetMetaModelNames

Metabase::GetMetaModelNames

LPDISPATCH GetMetaModelNames();

Return Value

The IDispatch pointer to a ValueList object that identiﬁes all DSS System names recorded in MetaCube’s metadata.

Remarks

Call this member function to identify the ValueList object that lists all DSS System names recorded in MetaCube’s metadata.

Metabase::GetParent

LPDISPATCH GetParent();

Return Value

The IDispatch pointer associated with the application object.

Remarks

Call this member function to identify the application object, which is required by OLE for multi-threading.

MetaCube Class Library 3-177 Metabase::GetPublicUser

Metabase::GetPublicUser

BSTR GetPublicUser();

Return Value

The OLE string identifying the user empowered to save queries and ﬁlters that other users can access.

Remarks

Call this member function to obtain the name of the user empowered to save queries and ﬁlters that other users can access in MetaCube Explorer and MetaCube for Excel. This string is set to “metapub” for current releases of Explorer and MetaCube for Excel.

Metabase::GetQueries

LPDISPATCH GetQueries();

Return Value

The IDispatch pointer associated with the Queries object, which is a collection of Query objects.

Remarks

Call this member function to identify the Queries object, a collection of all Query objects that have been saved with Query::SaveAs(), which saves a Query object with a name and associates that Query object with a folder.

3-178 SDK for Snap-Ins Programmer’s Manual Metabase::GetQueryBackJobs

Metabase::GetQueryBackJobs

LPDISPATCH GetQueryBackJobs();

Return Value

The IDispatch pointer associated with the QueryBackJobs object, which is a collection of QueryBackJob objects.

Remarks

Call this member function to identify the QueryBackJobs object, which is a collection of QueryBackJob objects. A QueryBackJob object is created when a query is submitted for background processing.

Metabase::GetRootFolder

LPDISPATCH GetRootFolder();

Return Value

The IDispatch pointer associated with the RootFolder object.

Remarks

Call this member function to identify the RootFolder object. The RootFolder object is a special folder that consists of only one object and can be the parent of other objects of a similar type. The RootFolder object represents the highest level object within the storage interface for queries and ﬁlters saved in MetaCube’s data.

MetaCube Class Library 3-179 Metabase::GetSchemas

Metabase::GetSchemas

LPDISPATCH GetSchemas();

Return Value

The IDispatch pointer associated with the Schemas object, which is a collection of Schema objects.

Remarks

Call this member function to identify the Schemas object, which is a collection of Schema objects identifying all the database schemas or table owners within the RDBMS. Objects in the Schemas collection represent a data dictionary of physical schemas, tables, and columns in the relational database. Schema objects do not store any of the corresponding multi-dimensional properties of these database structures. As such, the Schemas collection exists purely as a reference for supplying values to the objects in the FactTables and Dimensions collections, which map the relationship between physical structures and multi-dimensional terms and logic.

Metabase::GetSystemMessages

LPDISPATCH GetSystemMessages();

Return Value

The IDispatch pointer associated with the SystemMessages object.

Remarks

Call this member function to identify the SystemMessages object, which is a collection of SystemMessage objects. A SystemMessage object can be created to distribute a system message, such as the status of the database or a mainte- nance schedule, to the MetaCube family of applications.

3-180 SDK for Snap-Ins Programmer’s Manual Metabase::GetUniqueID

Metabase::GetUniqueID

long GetUniqueID();

Return Value

A long integer that is unique for each instance of a MetaCube analysis engine.

Remarks

Call this member function to obtain a unique identiﬁcation number, which is typically used in a multi-threading environment to ensure that multiple users do not get issued the same identiﬁcation number. Note that when using MetaCube SDK for Snap-Ins, the template .cpp code generated by the Extension Wizard supports multi-threading. No additional programming is necessary.

Metabase::ObjFromIDispatch

CCmdTarget* ObjFromIDispatch( LPDISPATCH dispatch );

Return Value

A pointer to the CCmdTarget object associated with dispatch.

Parameters dispatch A pointer to an IDispatch object

Remarks

Call this function to map an IDispatch pointer, received from automation member functions of a class, into the CCmdTarget object that implements the interfaces of the IDispatch object.

MetaCube Class Library 3-181 Metabase::OnClientTypeChanged

Metabase::OnClientTypeChanged

void OnClientTypeChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_clientType() has changed.

Metabase::OnConﬁgurationChanged

void OnConfigurationChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_conﬁguration() has changed.

Metabase::OnConnectDatabaseChanged

void OnConnectDatabaseChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_connectDatabase() has changed.

3-182 SDK for Snap-Ins Programmer’s Manual Metabase::OnConnectStringChanged

Metabase::OnConnectStringChanged

void OnConnectStringChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_connectString() has changed.

Metabase::OnDataSkipChanged

void OnDataSkipChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_dataSkip() has changed.

Metabase::OnExplainChanged

void OnExplainChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_explain() has changed.

MetaCube Class Library 3-183 Metabase::OnLocalMetamodelFileChanged

Metabase::OnLocalMetamodelFileChanged

void OnLocalMetamodelFileChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_localMetamodelFile() has changed.

Metabase::OnLoginChanged

void OnLoginChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_login() has changed.

Metabase::OnMetaSchemaChanged

void OnMetaSchemaChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_schema() has changed.

3-184 SDK for Snap-Ins Programmer’s Manual Metabase::OnNameChanged

Metabase::OnNameChanged

void OnNameChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_name() has changed.

Metabase::OnOptimizationChanged

void OnOptimizationChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_optimization() has changed.

Metabase::OnPasswordChanged

void OnPasswordChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_password() has changed.

MetaCube Class Library 3-185 Metabase::OnPDQPriorityChanged

Metabase::OnPDQPriorityChanged

void OnPDQPriorityChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_pDQPriority() has changed.

Metabase::OpenQuery

LPDISPATCH OpenQuery( LPCTSTR Name, LPCTSTR Author, LPDISPATCH aFolder );

Return Value

The IDispatch pointer associated with a Query object.

Parameters

Name Speciﬁes the name of a Query object for which a query deﬁnition is being retrieved.

Author Speciﬁes the user who created the Query object for which a query deﬁnition is being retrieved.

aFolder The IDispatch pointer associated with the Folder object that contains the Query object for which a query deﬁnition is being retrieved.

Remarks

Call this member function to instantiate a query deﬁnition stored in the metadata.

3-186 SDK for Snap-Ins Programmer’s Manual Metabase::OpenQueryStorage

Metabase::OpenQueryStorage

LPDISPATCH OpenQueryStorage( LPUNKNOWN Storage );

Return Value

The IDispatch pointer to a Query object.

Parameters

Storage Points to the structured storage object in which a Query object is saved

Remarks

Call this member function to return a pointer to a Query object saved in a structured storage object.

Metabase::OpenDSSSystem

void OpenDSSSystem();

Remarks

Call this member function to open a DSS System, as speciﬁed using the Get_m_name() member function. Calling this member function is equivalent to calling OpenDSSSystem2() with its Boolean value set to True.

MetaCube Class Library 3-187 Metabase::Save

Metabase::Save

void Save();

Remarks

Call this member function to save changes in a DSS System to the RDBMS metadata. The user running the extension that includes this member function must be a secure user. In other words, in MetaCube Secure Warehouse, that user must be granted authority to access Secure Warehouse and MetaCube Warehouse Manager.

Metabase::SaveAs

void SaveAs( LPCTSTR Name );

Parameters

Name Points to a string containing the name of the new DSS System

Remarks

Call this member function to save the current DSS System to the RDBMS metadata under a new name. The user running the extension that includes this member function must be a secure user. In other words, in MetaCube Secure Warehouse, that user must be granted authority to access Secure Warehouse and MetaCube Warehouse Manager.

3-188 SDK for Snap-Ins Programmer’s Manual MetaCube

MetaCube

CObject

CCmdTarget

COlapObject

MetaCube

A MetaCube object can be thought of as a virtual cube of data returned when a query is performed. The MetaCube class of objects provide different ways of organizing, summarizing, and pivoting that data. Query data can be represented in a break report, a cross-tabular report, or organized on different pages. While each new format or calculation manipulates the same set of data returned to the client, that format or calculation corresponds to a different MetaCube object within a Query object’s collection of MetaCube objects.

MetaCube Class Library 3-189 MetaCube Class Members

MetaCube Class Members

Operations

ClearSorts Cancels any sort assigned by the SetSortColumn() or SetSortRow() member functions

Copy Copies a MetaCube object and creates a new instance of that object with the same properties, orientations, sorts, and summaries as the source object

ErrorSpreadClip Returns a tab-delimited string containing the error data associated with a query result that has been extrapolated from a sample table

ErrorVBArray Returns a margin of error for each value in an extrapolated query result and assembles those error values into a two-dimensional variant array

FetchCell Returns the value of a speciﬁc cell

FetchCellError Returns a number indicating the range of error associated with a single value within an extrapolated query result

FetchCellType Identiﬁes the type of data in a speciﬁed cell

Get_m_column Identiﬁes a particular column in a virtual cube of data

Get_m_iparent Identiﬁes the Query object that contains a MetaCube object

Get_m_name Identiﬁes the name of a MetaCube object, as speciﬁed when the MetaCube object was created

Get_m_page Identiﬁes a particular page in a virtual cube of data

Get_m_row Identiﬁes a particular row in a virtual cube of data

Get_m_scratch Speciﬁes whether the MetaCube will be saved with the query’s deﬁnition

Get_m_sortColumnBreaks Speciﬁes whether MetaCube performs a numeric sort on sub-rows only, leaving rows unsorted

3-190 SDK for Snap-Ins Programmer’s Manual MetaCube Class Members

Operations

Get_m_sortColumnDirection Speciﬁes a sorting method for the column identiﬁed by the GetSortColumn() member function

Get_m_sortRowBreaks Speciﬁes whether MetaCube performs a numeric sort on sub-columns only, leaving columns unsorted

Get_m_sortRowDirection Speciﬁes a sorting method for the row identiﬁed by the GetSortRow() member function

Get_m_suppressDuplicates Speciﬁes whether duplicate values are suppressed in a report that includes rows and sub-rows or columns and sub-columns.

GetCell Returns the value of a speciﬁc cell

GetCellError Returns a number indicating the range of error associated with a single value within an extrapolated query result

GetCellType Identiﬁes the type of data in a speciﬁed cell

GetColumns Returns the number of columns in the virtual cube of data represented by a MetaCube object

GetCurrentAttribute Retrieves a pointer to a QueryCategory object containing the attribute or dimension element to which the currently selected or identiﬁed attribute or dimension value belongs

GetFormatStrings Retrieves a pointer to a ValueList object containing formatting commands for each numeric column or row in the query

GetPageLabels Retrieves a pointer to a ValueList object that stores the names of attribute values appearing in the page orientation for a particular page

GetPages Retrieves the number of pages in the virtual cube of data represented by the MetaCube object

GetRows Retrieves the number of rows in the virtual cube of data represented by a MetaCube object

MetaCube Class Library 3-191 MetaCube Class Members

Operations

GetSortColumn Identiﬁes a column of numeric data on which a sort will be performed

GetSortRow Identiﬁes a row of numeric data on which a sort will be performed

GetSummaries Retrieves a pointer to a Summaries object, which contains a collection of Summary objects

GetValue Returns the value of a speciﬁc cell

OnColumnChanged Issues a notiﬁcation that the value returned by Get_m_column() has changed

OnNameChanged Issues a notiﬁcation that the value returned by Get_m_name() has changed

OnPageChanged Issues a notiﬁcation that the value returned by Get_m_page() has changed

OnRowChanged Issues a notiﬁcation that the value returned by Get_m_row() has changed

OnSortColumnBreaksChanged Issues a notiﬁcation that the value returned by Get_m_sortColumnBreaks() has changed

OnSortColumnDirectionChanged Issues a notiﬁcation that the value returned by Get_m_sortColumnDirection() has changed

OnSortRowBreaksChanged Issues a notiﬁcation that the value returned by Get_m_sortRowBreaks() has changed

OnSortRowDirectionChanged Issues a notiﬁcation that the value returned by Get_m_sortRowDirection() has changed

OnSuppressDuplicatesChanged Issues a notiﬁcation that the value returned by Get_m_suppressDuplicates() has changed

SetSortColumn Speciﬁes a column of numeric data on which a sort will be performed

3-192 SDK for Snap-Ins Programmer’s Manual MetaCube Class Members

Operations

SetSortRow Speciﬁes a row of numeric data on which a sort will be performed

ToSpreadClip Returns a tab-delimited string that contains the data stored in the virtual cube represented by a MetaCube object

ToVBArray Translates the virtual cube of data represented by a MetaCube object into a two-dimensional variant array

MetaCube Class Library 3-193 MetaCube::ClearSorts

MetaCube::ClearSorts

void ClearSorts();

Remarks

Call this member function to cancel any sort assigned by the SetSortColumn() or SetSortRow() member functions. Note that this member function does not cancel sorts assigned by the QueryCategory object’s member function Get_m_sortDirection().

MetaCube::Copy

LPDISPATCH Copy();

Return Value

The IDispatch pointer to the new MetaCube object.

Remarks

Call this member function to copy a MetaCube object and create a new instance of a MetaCube object with the same properties, sorts, and summaries as the source object. When the new object is created, the value returned by Get_m_scratch() is nonzero, indicating the MetaCube object will not be saved with the query.

3-194 SDK for Snap-Ins Programmer’s Manual MetaCube::ErrorSpreadClip

MetaCube::ErrorSpreadClip

BSTR ErrorSpreadClip( long StartRow, long RowCount );

Return Value

An OLE string containing a tab-delimited string of error data associated with a query result that has been extrapolated from a sample table. If a query does not process against a sample table, this member function returns null values for all cells.

Parameters

StartRow Speciﬁes the row within the MetaCube object where the export of error data should begin. If no value is speciﬁed, error data is exported for all rows.

RowCount Speciﬁes the number of rows of error data that should be exported.

Remarks

When query results are extrapolated from a sample table, they include a range of error for each numeric value within the result. Call this member function to return a tab-delimited string that contains a page of error data associated with a query result that has been extrapolated from a sample table. Before calling this member function, the page should be speciﬁed by setting the return value referenced by Get_m_page(). Attribute values and other non-numeric cells within the report return null values. Null is represented in a tab-delimited string by two tabs with no value appearing between the tabs.

MetaCube Class Library 3-195 MetaCube::ErrorVBArray

MetaCube::ErrorVBArray

VARIANT ErrorVBArray();

Return Value

A VARIANT containing an OLE SafeArray. This member function returns null error values for queries that are not processed against a sample table. Non-numeric cells in a query result also return null error values regardless of the table from which the result was retrieved or derived.

Remarks

Call this member function to return a margin of error for each value on a page of an extrapolated query result. The error values for each value are assembled in a two-dimensional variant array that can be stored by a Visual Basic 4.0, Visual Basic for Applications, or C++/MFC variant or array variable. Before calling this member function, the page should be specified by setting the return value referenced by Get_m_page(). For numeric query results that are extrapolated from a sample table, the error value can be added or subtracted to the result, defining a range within which the actual value is likely to fall. The confidence with which MetaCube is required to certify that the actual result will fall within a certain range determines the size of the range. Calling this member function implicitly commands the MetaCube engine to execute a query.

3-196 SDK for Snap-Ins Programmer’s Manual MetaCube::FetchCell

MetaCube::FetchCell

VARIANT FetchCell( long Row, long Column, long Page );

Return Value

A variant containing whatever datatype the speciﬁed cell contains.

Parameters

Row Speciﬁes the row containing the desired cell.

Column Speciﬁes the column containing the desired cell.

Page Speciﬁes the page containing the desired cell.

Remarks

Call this member function to return as a variant the value of a speciﬁc cell within the virtual cube of data represented by a MetaCube object. Calling this member function before executing a query implicitly commands the MetaCube engine to execute the query. Note that calling this member function involves building the entire virtual cube of data on the client. Previously established limits on the number of rows a query can retrieve still apply.

MetaCube Class Library 3-197 MetaCube::FetchCellError

MetaCube::FetchCellError

double FetchCellError( long Row, long Column, long Page );

Return Value

A number of the double type indicating the error associated with a single value within an extrapolated query result. This member function returns a null error value if a query is not processed against a sample table. Non- numeric cells in a query result, such as cells containing attribute values, also return null error values.

Parameters

Row Speciﬁes the row containing the desired cell.

Column Speciﬁes the column containing the desired cell.

Page Speciﬁes the page containing the desired cell.

Remarks

Call this member function to return a number indicating the range of error associated with a single value within an extrapolated query result. For numeric query results that are extrapolated from a sample table, the error can be added or subtracted to the statistically predicted value, deﬁning a range within which the actual value is likely to fall. The conﬁdence with which MetaCube is required to certify that the actual result will fall within that range determines the size of the range. Calling this member function implicitly commands the MetaCube engine to execute a query.

3-198 SDK for Snap-Ins Programmer’s Manual MetaCube::FetchCellType

MetaCube::FetchCellType

long FetchCellType( long Row, long Column, long Page );

Return Value

A long integer indicating the type of data in a speciﬁed cell.

Parameters

Row Speciﬁes the row containing the desired cell.

Column Speciﬁes the column containing the desired cell.

Page Speciﬁes the page containing the desired cell.

Remarks

Call this member function to return a long integer identifying the type of data in a specified cell. The metacons.h file defines constants for the possible types of cell data. The following table duplicates the cell type constants listed in metacons.h.:

Cell Contents Name in Metacons.h Constant

Empty CellTypeEmpty 0

QueryCategory name CellTypeCategoryLabel 1

QueryCategory value CellTypeCategoryValue 2

Label for column or row containing CellTypeSummaryLabel 3 calculated information

Calculated data, such as subtotals or CellTypeSummaryValue 4 grand totals

Measure name CellTypeQueryItemLabel 5

Numeric measure value CellTypeQueryItemValue 6

MetaCube Class Library 3-199 MetaCube::Get_m_column

MetaCube::Get_m_column

long& Get_m_column();

Return Value

A reference to a long integer indicating a column in a virtual cube of data.

Remarks

Set the return value of this member function to specify a particular column in a virtual cube of data represented by a MetaCube object.

MetaCube::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A reference to a pointer to the Query object that contains a MetaCube object.

Remarks

Use this member function to identify the Query object that contains a MetaCube object.

3-200 SDK for Snap-Ins Programmer’s Manual MetaCube::Get_m_page

MetaCube::Get_m_page

long& Get_m_page();

Return Value

A reference to a long integer indicating a page in a virtual cube of data.

Remarks

Set the return value of this member function to identify a particular page in a virtual cube of data represented by a MetaCube object.

MetaCube::Get_m_name

CString& Get_m_name();

Return Value

A reference to a string containing the name of a MetaCube object.

Remarks

Set the return value of this member function to retrieve the name of a MetaCube object, as speciﬁed when the MetaCube object was created.

MetaCube Class Library 3-201 MetaCube::Get_m_row

MetaCube::Get_m_row

long& Get_m_row();

Return Value

A reference to a long integer indicating a row in a virtual cube of data.

Remarks

Set the return value of this member function to specify a particular row in a virtual cube of data represented by a MetaCube object.

MetaCube::Get_m_scratch

BOOL& Get_m_scratch();

Return Value

A reference to a Boolean value. Nonzero, the default, indicates that the MetaCube object, including its subtotals and sorts, will not be saved with the query’s deﬁnition. Zero indicates that the MetaCube object is saved when the query is saved.

Remarks

Set the return value of this member function to specify whether the MetaCube, including its subtotals and sorts, will be saved with the query’s deﬁnition.

3-202 SDK for Snap-Ins Programmer’s Manual MetaCube::Get_m_sortColumnBreaks

MetaCube::Get_m_sortColumnBreaks

BOOL& Get_m_sortColumnBreaks();

Return Value

A reference to a Boolean value. Nonzero indicates that MetaCube performs a numeric sort on rows within each break. Zero, the default value, indicates that MetaCube sorts the entire report so that the smallest measure values appear ﬁrst and the largest last, or vice-versa, regardless of the break to which a row belongs.

Remarks

Set the return value of this member function to specify whether MetaCube sorts rows within a break or sorts rows without regard to breaks. A break report lists values for multiple attributes and sorts them according to one or more of those attributes. For example, a break report might list the Units Sold by Region and break each region’s sales out according to the Brand attribute, as shown in Figure 19.

Figure 19 Sorting Rows

Rows sorted by measure Rows sorted by measure within each break

MetaCube Class Library 3-203 MetaCube::Get_m_sortColumnDirection

MetaCube::Get_m_sortColumnDirection

long& Get_m_sortColumnDirection();

Return Value

A reference to a constant that determines how a column is sorted.

Remarks

Set the return value of this member function to specify a sorting method for the column identified by GetSortColumn(). An ascending sort arranges numbers so the largest appear at the bottom of a report. The metacons.h file defines possible sorting methods and assigns a constant to each method. The following table duplicates the sorting information listed in metacons.h:

Sort Direction Name in Metacons.h Constant

No Sort SortDirectionIgnore 0

Ascending Order SortDirectionAsc 1 (default value)

Descending Order SortDirectionDesc 2

3-204 SDK for Snap-Ins Programmer’s Manual MetaCube::Get_m_sortRowBreaks

MetaCube::Get_m_sortRowBreaks

BOOL& Get_m_sortRowBreaks();

Return Value

A reference to a Boolean value. Nonzero indicates that MetaCube performs a numeric sort on columns within each break. Zero, the default value, indicates that MetaCube sorts the entire report so that the smallest measure values appear ﬁrst and the largest last, or vice-versa, regardless of the break to which a column belongs.

Remarks

Set the return value of this member function to specify whether MetaCube sorts columns within a break or sorts columns without regard to breaks. A break report lists values for multiple attributes and sorts them according to one or more of those attributes. For example, a break report might list the Units Sold by Region and break those sales out according to the Brand attribute.

MetaCube Class Library 3-205 MetaCube::Get_m_sortRowDirection

MetaCube::Get_m_sortRowDirection

long& Get_m_sortRowDirection();

Return Value

A reference to a constant that determines how a row is sorted.

Remarks

Set the return value of this member function to specify a sorting method for the row identified by GetSortRow(). An ascending sort arranges numbers so the largest appear in columns to the right of the report and the smallest appear in columns to the left. The metacons.h file defines possible sorting methods and assigns a constant to each method. The following table duplicates the sorting information listed in metacons.h:

Sort Direction Name in Metacons.h Constant

No Sort SortDirectionIgnore 0

Ascending Order SortDirectionAsc 1 (default value)

Descending Order SortDirectionDesc 2

3-206 SDK for Snap-Ins Programmer’s Manual MetaCube::Get_m_suppressDuplicates

MetaCube::Get_m_suppressDuplicates

BOOL& Get_m_suppressDuplicates();

Return Value

A reference to a Boolean value. Nonzero indicates that duplicate values are suppressed in a report that includes rows and sub-rows or columns and sub- columns. Zero, the default value, indicates that row or column values are duplicated for each value within a sub-row or sub-column.

Remarks

Set the return value of this member function to specify whether duplicate values are suppressed in a break report that includes rows and sub-rows or columns and sub-columns. A break report includes sub-rows or sub-columns when a query is performed on multiple attributes, such as Region and Brand.

MetaCube Class Library 3-207 MetaCube::GetCell

MetaCube::GetCell

VARIANT GetCell();

Return Value

A variant containing whatever datatype the speciﬁed cell contains.

Remarks

Call this member function to return as a variant the value of a speciﬁc cell within the virtual cube of data represented by a MetaCube object. Use the Get_m_row(), Get_m_column(), and Get_m_page() member functions to specify the cell. Calling this member function before executing a query implicitly commands the MetaCube engine to execute the query. Note that calling this member function involves building the entire virtual cube of data on the client. Previously established limits on the number of rows a query can retrieve still apply.

3-208 SDK for Snap-Ins Programmer’s Manual MetaCube::GetCellError

MetaCube::GetCellError

double GetCellError();

Return Value

A double indicating the range of error associated with the value of a cell. If sampling was not used when this MetaCube object was generated, this member function returns zero.

Remarks

Call this member function to return the range of error associated with the value of a particular cell when query results have been extrapolated from a sample table. The conﬁdence with which MetaCube is required to certify that the actual result will fall within a range of error determines the size of the range. Use the Get_m_row(), Get_m_column(), and Get_m_page() member functions to specify the cell for which a range of error is being retrieved. Note that calling this member function involves building the entire virtual cube of data on the client. Previously established limits on the number of rows a query can retrieve still apply.

MetaCube Class Library 3-209 MetaCube::GetCellType

MetaCube::GetCellType

long GetCellType();

Return Value

A long integer indicating the type of data in a speciﬁed cell.

Remarks

Call this member function to return a long integer identifying the type of data in a specified cell. Use the Get_m_row(), Get_m_column(), and Get_m_page() member functions to specify the cell. The metacons.h file defines constants for the possible types of cell data. The following table duplicates the cell type constants listed in metacons.h.:

Cell Contents Name in Metacons.h Constant

Empty CellTypeEmpty 0

QueryCategory name CellTypeCategoryLabel 1

QueryCategory value CellTypeCategoryValue 2

Label for column or row containing CellTypeSummaryLabel 3 calculated information

Calculated data, such as subtotals or CellTypeSummaryValue 4 grand totals

Measure name CellTypeQueryItemLabel 5

Numeric measure value CellTypeQueryItemValue 6

The value returned by this member function cannot be changed because the type of cell depends on the deﬁnition of the query and the format of the report.

3-210 SDK for Snap-Ins Programmer’s Manual MetaCube::GetColumns

MetaCube::GetColumns

long GetColumns();

Return Value

A long integer providing the number of columns in the virtual cube of data represented by a MetaCube object.

Remarks

Call this member function to return a long integer providing the number of columns in the virtual cube of data represented by a MetaCube object. The number of columns depends on the number of attributes, measures, and dimension elements included in a query and the range of values represented by each attribute, measure, or dimension element. Thus the value returned by this member function cannot be changed.

MetaCube Class Library 3-211 MetaCube::GetCurrentAttribute

MetaCube::GetCurrentAttribute

LPDISPATCH GetCurrentAttribute();

Return Value

The IDispatch pointer to a QueryCategory object containing an attribute, dimension element, or function call.

Remarks

Call this member function to retrieve a pointer to a QueryCategory object containing the attribute, dimension element, or function call to which the currently selected or identiﬁed value belongs.

3-212 SDK for Snap-Ins Programmer’s Manual MetaCube::GetFormatStrings

MetaCube::GetFormatStrings

LPDISPATCH GetFormatStrings();

Return Value

The IDispatch pointer to a ValueList object containing formatting commands for each numeric column or row in the query.

Remarks

Call this member function to retrieve a ValueList object containing formatting commands for each numeric column or row in the query. QueryItem::Get_m_formatString() determines the formatting commands for each numeric row or column. Query::GetItemOrientation() determines whether measures are listed by row or by column.

MetaCube::GetPageLabels

LPDISPATCH GetPageLabels();

Return Value

The IDispatch pointer to a ValueList object that stores the names of attribute values appearing in the page orientation for a particular page.

Remarks

Call this member function to retrieve a pointer to a ValueList object that stores the names of attribute values appearing in the page orientation for a particular page. The Get_m_page() member function identiﬁes the page for which attribute values are being retrieved. The ValueList object retrieved by this member function will contain multiple values if more than one Query- Category has been pivoted to a page orientation.

MetaCube Class Library 3-213 MetaCube::GetPages

MetaCube::GetPages

long GetPages();

Return Value

A long integer representing the number of pages in the virtual cube of data.

Remarks

Call this member function to retrieve a long integer representing the number of pages in the virtual cube of data represented by the MetaCube object.

MetaCube::GetRows

long GetRows();

Return Value

A long integer providing the number of rows in the virtual cube of data.

Remarks

Call this member function to retrieve the number of rows in the virtual cube of data represented by a MetaCube object. The value returned by this member function cannot be changed because the number of rows in the virtual cube depends on the deﬁnition of the query and the number of records retrieved by the query.

3-214 SDK for Snap-Ins Programmer’s Manual MetaCube::GetSortColumn

MetaCube::GetSortColumn

long GetSortColumn();

Return Value

A long integer indicating the column of numeric data on which a sort will be performed.

Remarks

Call this member function to identify a column of numeric data on which a sort will be performed.

MetaCube::GetSortRow

long GetSortRow();

Return Value

A long integer indicating the row of numeric data on which a sort will be performed.

Remarks

Call this member function to identify a row of numeric data on which a sort will be performed.

MetaCube Class Library 3-215 MetaCube::GetSummaries

MetaCube::GetSummaries

LPDISPATCH GetSummaries();

Return Value

The IDispatch pointer to a Summaries object.

Remarks

Call this member function to retrieve a pointer to a Summaries object, which contains a collection of Summary objects. Summary objects represent break reports, in which calculations are performed on attribute values within a larger grouping of attribute values.

MetaCube::GetValue

VARIANT GetValue();

Return Value

A variant containing whatever datatype the speciﬁed cell contains.

Remarks

3-216 SDK for Snap-Ins Programmer’s Manual MetaCube::OnColumnChanged

MetaCube::OnColumnChanged

void OnColumnChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_column() has changed.

MetaCube::OnNameChanged

void OnNameChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_name() has changed.

MetaCube::OnPageChanged

void OnPageChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_page() has changed.

MetaCube Class Library 3-217 MetaCube::OnRowChanged

MetaCube::OnRowChanged

void OnRowChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_row() has changed.

MetaCube::OnSortColumnBreaksChanged

void OnSortColumnBreaksChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_sortColumnBreaks() has changed.

MetaCube::OnSortColumnDirectionChanged

void OnSortColumnDirectionChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_sortColumnDirection() has changed.

3-218 SDK for Snap-Ins Programmer’s Manual MetaCube::OnSortRowBreaksChanged

MetaCube::OnSortRowBreaksChanged

void OnSortRowBreaksChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_sortRowBreaks() has changed.

MetaCube::OnSortRowDirectionChanged

void OnSortRowDirectionChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_sortRowDirection() has changed.

MetaCube::OnSuppressDuplicatesChanged

void OnSuppressDuplicatesChanged();

Return Value

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_suppressDuplicates() has changed.

MetaCube Class Library 3-219 MetaCube::SetSortColumn

MetaCube::SetSortColumn

void SetSortColumn( long nNewValue );

Parameters

nNewValue A long integer specifying the column of numeric data on which a sort will be performed. The default value is -1, which directs MetaCube to sort reports using the sorting approach speciﬁed with QueryCategory::Get_m_sort- Direction().

Remarks

Call this member function to specify the column of numeric data on which a sort will be performed. Rows are sorted according to the numeric value of the measure appearing in each row in the specified column. Columns are numbered left to right beginning with zero at the first column in the report. Pivoting measures to the row orientation does not alter the value returned by this member function. Any value set using this member function overrides any sort applied to a QueryCategory object organized by rows because SetSortColumn() sorts rows based on the values of a measure rather than the value of an attribute. Unlike QueryCategory::Get_m_sortDirection(), which allows you to sort attribute values regardless of their position in the report, SetSortColumn() allows you to apply a new sort to an arbitrary numeric column within an existing report. Specifying the column on which to base a sort of rows prior to processing a query can be difficult, however, because the order in which columns appear depends on the query result. In cases where MetaCube sorts numeric data on rows and columns before the query executes, rows are sorted first. Using this member function to specify a column of attribute values returns an error.

3-220 SDK for Snap-Ins Programmer’s Manual MetaCube::SetSortRow

MetaCube::SetSortRow

void SetSortRow( long nNewValue );

Parameters nNewValue A long integer specifying the row of numeric data on which a sort will be performed. The default value is -1, which directs MetaCube to sort reports using the sorting approach speciﬁed with QueryCategory::Get_m_sortDirection().

Remarks

Call this member function to specify the row of numeric data on which a sort will be performed. Columns are sorted according to the numeric value of the measure appearing in each column. Rows are numbered from top to bottom beginning with zero at the first row in the report. Any value set using this member function overrides any sort applied to a QueryCategory object organized by columns because SetSortRow() sorts columns based on the values of a measure rather than the value of an attribute. Because a QueryCategory object is sorted before numeric data is sorted, changing the sort on a QueryCategory object organized by rows changes the values that appear in any given row specified by this member function. This property allows you to apply a new sort to an existing report. Specifying the row on which to base a sort of columns prior to processing a query can be difficult, however, because the order in which rows appear depends on the query result. In cases where MetaCube sorts numeric data on rows and columns before the query executes, rows are sorted first. Using this member function to specify a row of attribute values returns an error.

MetaCube Class Library 3-221 MetaCube::ToSpreadClip

MetaCube::ToSpreadClip

BSTR ToSpreadClip( long StartRow, long RowCount );

Return Value

An OLE string containing a tab-delimited string containing the data in the virtual cube represented by a MetaCube object.

Parameters

StartRow Speciﬁes the row within the MetaCube object where the export of data should begin. If no value is speciﬁed, data is exported for all rows.

RowCount Speciﬁes the number of rows of data that should be exported.

Remarks

Call this member function to return a tab-delimited string that contains a page of data stored in the virtual cube represented by a MetaCube object. Before calling this member function, the page should be speciﬁed by setting the return value referenced by Get_m_page(). Calling this member function before executing a query implicitly commands the MetaCube engine to execute the query.

3-222 SDK for Snap-Ins Programmer’s Manual MetaCube::ToVBArray

MetaCube::ToVBArray

VARIANT ToVBArray();

Return Value

A VARIANT containing an OLE SafeArray.

Remarks

Call this member function to translate a page in the virtual cube of data represented by a MetaCube object into a two-dimensional variant array that can be stored by a Visual Basic 4.0, Visual Basic for Applications, or C++/MFC variant or array variable. Before calling this member function, the page should be speciﬁed by setting the return value referenced by Get_m_page(). Calling this member function implicitly commands the MetaCube engine to execute a query.

MetaCube Class Library 3-223 MetaCubes

MetaCubes

CObject

CCmdTarget

COlapObject

COleCollection

MetaCubes

The MetaCubes class of objects manages collections of MetaCube objects. The MetaCubes member functions allow you to create and delete MetaCube objects and to identify the Query object containing a collection of MetaCube objects.

MetaCubes Class Members

Operations

Add Instantiates a new MetaCube object, adds it to the collection of MetaCube objects, and returns the new object

Get_m_iparent Identiﬁes the Query object that contains a collection of MetaCube objects

Remove Removes a MetaCube object from a collection of MetaCube objects

3-224 SDK for Snap-Ins Programmer’s Manual MetaCubes::Add

MetaCubes::Add

LPDISPATCH Add( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new MetaCube object.

Parameters

Name Pointer to the text string that is the name of the new MetaCube object.

Remarks

Call this member function to instantiate a new MetaCube object, which adds the new MetaCube object to a collection of MetaCube objects and returns the name of the new MetaCube object.

MetaCubes::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the Query object that contains a collection of MetaCube objects.

Remarks

Use this member function to identify the Query object that contains a collection of MetaCube objects.

MetaCube Class Library 3-225 MetaCubes::Remove

MetaCubes::Remove

void Remove( const VARIANT FAR& index );

Parameters

index A constant representing the MetaCube object to be removed from the collection of MetaCube objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a MetaCube object from a collection of MetaCube objects.

3-226 SDK for Snap-Ins Programmer’s Manual Queries

Queries

CObject

CCmdTarget

COlapObject

COleCollection

Queries

The Queries class of objects manages collections of Query objects. A Query object contains a collection of attributes, measures, ﬁlters, and multi-dimensional results. The Queries member functions allow you to add new Query objects to the collection and remove Query objects.

Queries Class Members

Operations

Add Adds a new instance of a Query object to this collection and returns a pointer to that new object

Get_m_iparent Identiﬁes the Metabase object that contains this collection of Query objects

Remove Removes a Query object from a collection of Query objects

MetaCube Class Library 3-227 Queries::Add

Queries::Add

LPDISPATCH Add( LPCTSTR name );

Return Value

The IDispatch pointer for the Query object being created.

Parameters

name Points to the text string that is the name of the Query object being created

Remarks

Call this member function to create a Query object, which adds that query to the collection of Query objects and returns a pointer to the new Query object.

Queries::Get_m_iparent

class Metabase*& Get_m_iparent();

Return Value

A pointer to the Metabase object that contains this collection of Query objects.

Remarks

Use this member function to identify the Metabase object that contains this collection of Query objects.

3-228 SDK for Snap-Ins Programmer’s Manual Queries::Remove

Queries::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the Query object to be removed from the collection of Query objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a Query object from a collection of Query objects.

MetaCube Class Library 3-229 Query

Query

CObject

CCmdTarget

COlapObject

Query

The Query class of objects represents a collection of QueryCategory, QueryItem, MetaCube and Filter object collections. You can manipulate those collections to deﬁne the data you want to retrieve from a database. Query deﬁnitions that include a QueryItem object retrieve transaction-based data. Queries that include only QueryCategory objects retrieve data about the relationships within a dimensional hierarchy. Transaction-based queries (those including a QueryItem) must include at least one QueryCategory object by which transactions are grouped, although they can potentially include an unlimited number of QueryCategory objects.

3-230 SDK for Snap-Ins Programmer’s Manual Query Class Members

Query Class Members

Operations

ClearParameters Erases any values previously applied to the parameters in a query

DeleteQuery Deletes a query deﬁnition from the database

Get_m_accuracy Speciﬁes the degree of accuracy with which MetaCube should attempt to process a query

Get_m_author Identiﬁes the author of a query

Get_m_autoRefresh Speciﬁes whether a query should re-execute automatically

Get_m_confidence Specifies the statistical confidence with which MetaCube will report results extrapolated from sample tables

Get_m_dataSource Speciﬁes the data source for which a query is being deﬁned

Get_m_iparent Identiﬁes the Metabase object that is the parent of this Query object

Get_m_itemOrientation Determines whether measures returned by a query are being displayed as rows, columns, or pages

Get_m_name Retrieves the name of a Query object

Get_m_qcube Retrieves a pointer to the CQueryCube object that the database has generated for this query

Get_m_referenceCount Retrieves the current value of the counter maintained by the Query object

Get_m_saved Determines whether a query, as currently deﬁned, is saved in the database

GetCost Retrieves a long integer representing the relative performance cost of executing this query, as returned by the MetaCube Optimizer for any valid transactional query before or after execution

GetCurrentData Determines if MetaCube has executed a query and the results reside in local memory

MetaCube Class Library 3-231 Query Class Members

Operations

GetDrillDataSources Identiﬁes the FactTable objects that a query can access

GetExecutionTime Retrieves the length of time required to execute a query

GetFilters Retrieves a pointer to a collection of saved or unsaved ﬁlters that have been applied to the query’s deﬁnition

GetFolder Retrieves a pointer to the Folder object within which the Query object has been saved

GetItemOrientation Determines whether measures returned by a query are being displayed as rows, columns, or pages

GetLastSaved Retrieves the date and time when the query was last saved

GetLastUpdate Retrieves the date and time when the query was last changed

GetLive Determines whether a Metabase object deﬁnes a connection to a database so the query can be executed

GetMaximumExceeded Determines whether an executing query returned a number of rows that exceeded the limit set by Metabase::Get_m_maxTotalFetches()

GetMetaCubes Retrieves a pointer to the collection of MetaCube objects associated with this query

GetName Retrieves the name of a Query object

GetParameterObject Identifies the QueryCategory object included in the filter definition for a specified parameter

GetParameterOperator Retrieves the operator for an undeﬁned parameter

GetParameters Retrieves the ValueList object containing all undeﬁned ﬁlter parameters for the query

GetQueryCategories Retrieves a pointer to the query’s collection of QueryCat- egory objects

GetQueryItems Retrieves a pointer to the query’s collection of QueryItem objects

3-232 SDK for Snap-Ins Programmer’s Manual Query Class Members

Operations

GetSQL Retrieves a pointer to the ValueList object containing the SQL generated by the MetaCube engine for any valid query

GetTimeFiltered Determines if a query includes a ﬁlter on time

OnAccuracyChanged Issues a notiﬁcation to MetaCube that the value referenced by Get_m_accuracy() has changed

OnConfidenceChanged Issues a notification to MetaCube that the value referenced by Get_m_confidence() has changed

OnDataSourceChanged Issues a notiﬁcation to MetaCube that the value referenced by Get_m_dataSource() has changed

Retrieve Commands MetaCube to transmit the SQL generated for the query directly to the relational database

Save Saves the query deﬁnition that is currently held in memory into the metadata tables in the relational database

SaveAs Saves the query deﬁnition currently stored in memory into metadata tables in the relational database and assigns the query a new name, and stores it in a different folder

SaveStorage Saves a Query object in a structured storage object

SetItemOrientation Sets the orientation of measures returned by a query

SetName Changes the name of the Query object

SetParameter Assigns a value or values to a ﬁlter parameter

SetSQL Replaces an SQL statement that was generated by the MetaCube engine for any valid query

Submit Submits an object for background processing, which instantiates a QueryBackJob object

MetaCube Class Library 3-233 Query::ClearParameters

Query::ClearParameters

void ClearParameters();

Remarks

Call this member function to erase any values a procedure previously applied to the parameters in a query. This member function does not bypass or erase parameters values created in MetaCube Agent Administrator, which always override parameters assigned by the application.

Query::DeleteQuery

void DeleteQuery();

Remarks

Call this member function to delete a query deﬁnition from the database.

3-234 SDK for Snap-Ins Programmer’s Manual Query::Get_m_accuracy

Query::Get_m_accuracy

long& Get_m_accuracy();

Return Value

A reference to a number between 1 and 100 indicating the degree of accuracy with which MetaCube should attempt to process a query.

Remarks

Set the return value of this member function to specify the degree of accuracy with which MetaCube should attempt to process a query. Any value less than 100 prompts MetaCube to process the query against a sample table. The range of accuracy requested for the query directs MetaCube to extrapolate a result from a larger or smaller sample table.

Query::Get_m_author

CString& Get_m_author();

Return Value

A string identifying the author of a query.

Remarks

Call this member function to identify the author of a query. By default, this member function will return the name of the database user provided at login.

MetaCube Class Library 3-235 Query::Get_m_autoRefresh

Query::Get_m_autoRefresh

BOOL& Get_m_autoRefresh();

Return Value

A reference to a Boolean value. Nonzero indicates a query should re-execute. Zero indicates the query should not re-execute.

Remarks

Set the return value of this member function to specify whether a query should re-execute automatically.

3-236 SDK for Snap-Ins Programmer’s Manual Query::Get_m_conﬁdence

Query::Get_m_conﬁdence

long& Get_m_confidence();

Return Value

A reference to a number between 1 and 100 indicating the statistical conﬁ- dence with which MetaCube will report results extrapolated from sample tables.

Remarks

Set the return value of this member function to specify the statistical confidence with which MetaCube will report results extrapolated from sample tables. As the value of this property increases, the range of error values also increases. For example, MetaCube may be able to predict with 80 percent confidence that a number falls between 210 and 230. It may predict with only 50 percent confidence that the number falls between 215 and 225. The following member functions of the MetaCube object class return information about the margin of error for a sampled report:

■ FetchCellError() ■ GetCellError() ■ ErrorVBArray() ■ ErrorSpreadClip()

MetaCube Class Library 3-237 Query::Get_m_dataSource

Query::Get_m_dataSource

CString& Get_m_dataSource();

Return Value

A reference to a string describing the data source or data sources for which a query is being deﬁned.

Remarks

Set the return value of this member function to specify the data source (that is, the fact table) for which a query is being defined. MetaCube does not use the information specified by this member function when generating SQL for a query. Instead, it uses data specified by the QueryCategory and QueryItem objects. MetaCube Explorer uses the value returned by this member function.

Query::Get_m_iparent

class Metabase*& Get_m_iparent();

Return Value

A pointer to the Metabase object that is the parent of this Query object.

Remarks

Use this member function to identify the Metabase object that is the parent of this Query object.

3-238 SDK for Snap-Ins Programmer’s Manual Query::Get_m_itemOrientation

Query::Get_m_itemOrientation

long& Get_m_itemOrientation();

Return Value

A reference to a long integer that determines how measures returned by the query are displayed.

Remarks

Set the value returned by this member function to determine whether measures returned by a query are displayed as rows, columns, or pages. The metacons.h ﬁle assigns a constant to each possible orientation. The following table duplicates the orientation information listed in metacons.h:

Orientation Name in Metacons.h Constant

Rows OrientationRow 1

Columns OrientationColumn 2

Pages OrientationPage 3

MetaCube Class Library 3-239 Query::Get_m_name

Query::Get_m_name

CString& Get_m_name();

Return Value

A reference to the string containing the name of the Query object.

Remarks

Call this member function to retrieve the name of a Query object, which is speciﬁed as an argument when a Query object is instantiated. To change the name of a Query object, call SetName().

Query::Get_m_qcube

CQueryCube*& Get_m_qcube();

Return Value

A pointer to the CQueryCube object generated for this query. If a query has never been run, this member function returns null.

Remarks

Call this member function retrieve a pointer to the CQueryCube object, which is a multi-dimensional data object that holds the results of this query.

3-240 SDK for Snap-Ins Programmer’s Manual Query::Get_m_referenceCount

Query::Get_m_referenceCount

long& Get_m_referenceCount();

Return Value

A reference to a counter that the Query object maintains.

Remarks

Call this member function to retrieve the current value of the counter maintained by the Query object. Programmers can use this counter for reference purposes. This member function is not the same as COlapObject::GetRefCount().

Query::Get_m_saved

BOOL& Get_m_saved();

Return Value

A reference to a Boolean value. Nonzero indicates the query, as currently deﬁned, is saved in the database. Zero indicates the query’s current deﬁnition is not saved.

Remarks

Call this member function to determine whether a query, as currently deﬁned, is saved in the database. You should not set the value returned by this member function.

MetaCube Class Library 3-241 Query::GetCost

Query::GetCost

long GetCost();

Return Value

A long integer representing the relative performance cost of executing this query.

Remarks

Call this member function to retrieve a long integer representing the relative performance cost of executing this query, as returned by the MetaCube Optimizer for any valid transactional query before or after execution. This value reﬂects the size of the aggregate table, fact table, or sample table chosen by the MetaCube engine to answer the query. Although this value generally corresponds to the number of rows in the table, its scale ultimately depends on how the metadata for those tables has been deﬁned. Costs are additive; the cost of queries consisting of multiple SQL statements or SQL statements accessing multiple fact or aggregate tables is the sum of the costs for each of the tables that must be accessed.

3-242 SDK for Snap-Ins Programmer’s Manual Query::GetCurrentData

Query::GetCurrentData

BOOL GetCurrentData();

Return Value

A Boolean value. Nonzero indicates that MetaCube has executed the query as currently deﬁned and the results reside in local memory. Zero indicates MetaCube has not executed the query or the result does not reside in local memory.

Remarks

Call this member function to determine if MetaCube has executed a query and the results reside in local memory.

MetaCube Class Library 3-243 Query::GetDrillDataSources

Query::GetDrillDataSources

LPDISPATCH GetDrillDataSources();

Return Value

An IDispatch pointer to the DrillDataSources collection, which is a collection of FactTable objects that can be accessed by a query.

Remarks

Call this member function to identify the FactTable objects that a query can access. A query can access measure information from any fact table that contains the dimensions included in the query, but the query cannot access the appropriate measure information from any fact table that does not contain the dimensions included in the query. The DrillDataSources collection shows the FactTable objects that can potentially be added to a query. It lists the FactTable objects that contain the dimensions already included in the query. The DrillDataSources collection is available only for reference; applications cannot instantiate a new item in the collection and the DrillDataSources collection has no Add member function.

3-244 SDK for Snap-Ins Programmer’s Manual Query::GetExecutionTime

Query::GetExecutionTime

VARIANT GetExecutionTime();

Return Value

A type that provides the length of time required to execute a query. If the query is pending execution, null is returned.

Remarks

Call this member function to retrieve the length of time required to execute a query, as incremented from 12:00:00 A.M.

Query::GetFilters

LPDISPATCH GetFilters();

Return Value

An IDispatch pointer to a collection of saved or unsaved ﬁlters that have been applied to the query’s deﬁnition.

Remarks

Call this member function to retrieve a pointer to a collection of saved or unsaved filters that have been applied to the query’s definition. Any unsaved filters designed for a particular query exist only within this collection until they are saved.

MetaCube Class Library 3-245 Query::GetFolder

Query::GetFolder

LPDISPATCH GetFolder();

Return Value

An IDispatch pointer to the Folder object within which the Query object was last saved. If the Query object has not been saved, null is returned.

Remarks

Call this member function to retrieve a pointer to the Folder object within which the Query object was last saved.

3-246 SDK for Snap-Ins Programmer’s Manual Query::GetItemOrientation

Query::GetItemOrientation

long GetItemOrientation();

Return Value

A constant that indicates how measures returned by the query are being displayed.

Remarks

Call this member function to determine whether measures returned by a query are being displayed as rows, columns, or pages. The metacons.h ﬁle assigns a constant to each possible type of orientation. The following table duplicates the orientation information listed in metacons.h:

Orientation Name in Metacons.h Constant

Rows OrientationRow 1

Columns OrientationColumn 2

To change the orientation of measures returned by a query, call SetItemOrientation().

MetaCube Class Library 3-247 Query::GetLastUpdate

Query::GetLastUpdate

VARIANT GetLastUpdate();

Return Value

A type that provides the date and time when the query was last changed.

Remarks

Call this member function to retrieve the date and time when the query was last changed.

Query::GetLive

BOOL GetLive();

Return Value

A Boolean value. Nonzero indicates a connection to a database has been established to execute the query as it is currently deﬁned. Zero indicates the query has been deﬁned using a connection to some other database.

Remarks

Call this member function to determine whether a Metabase object deﬁnes a connection to the correct database for the query to be executed. A query can be deﬁned for another database to which MetaCube is not currently connected but that query cannot be run until MetaCube is connected to the appropriate database.

3-248 SDK for Snap-Ins Programmer’s Manual Query::GetMaximumExceeded

Query::GetMaximumExceeded

BOOL GetMaximumExceeded();

Return Value

A Boolean value. Nonzero indicates that the query has returned a number of rows exceeding the limit set by Metabase::Get_m_maxTotalFetches(). Zero indicates that limit has not been exceeded.

Remarks

Call this member function to determine whether an executing query returned a number of rows that exceeded the limit set by Metabase::Get_m_maxTotal- Fetches().

Query::GetMetaCubes

LPDISPATCH GetMetaCubes();

Return Value

An IDispatch pointer to a collection of MetaCube objects.

Remarks

Call this member function to retrieve a pointer to the collection of MetaCube objects associated with this query. A MetaCube object presents a multi- dimensional representation of a query result. This representation is often called a virtual cube of data.

MetaCube Class Library 3-249 Query::GetName

Query::GetName

BSTR GetName();

Return Value

An OLE string containing the name of the Query object.

Remarks

Call this member function to retrieve the name of a Query object, which is speciﬁed as an argument when a Query object is instantiated. To change the name of an existing Query object, call SetName().

Query::GetParameterObject

LPDISPATCH GetParameterObject( long index );

Return Value

An IDispatch pointer to a QueryCategory object.

Parameters

index The 0-based index specifying the parameter for which a QueryCategory object is necessary.

Remarks

Call this member function to identify the QueryCategory object included in the filter definition for a specified parameter. Calling QueryCat- egory::Get_m_category() for that object returns the string containing the name of an Attribute or DimensionElement object or the syntax of an expression. This information can be used to identify the values that must be supplied to complete the filter.

3-250 SDK for Snap-Ins Programmer’s Manual Query::GetParameterOperator

Query::GetParameterOperator

BSTR GetParameterOperator( long index );

Return Value

An OLE string containing the operator for an undeﬁned parameter.

Parameters index The 0-based index specifying a particular undeﬁned parameter

Remarks

Call this member function to retrieve the operator for an undeﬁned parameter.

Query::GetParameters

LPDISPATCH GetParameters();

Return Value

An IDispatch pointer to a ValueList object containing all undeﬁned ﬁlter parameters for the query.

Remarks

Call this member function to retrieve the ValueList object containing all undefined filter parameters for the query. These undefined filter parameters are strings containing user prompts, such as <>. The ValueList object does not contain parameters that were previously defined by MetaCube Agent Administrator, the application, or the user.

MetaCube Class Library 3-251 Query::GetQueryCategories

Query::GetQueryCategories

LPDISPATCH GetQueryCategories();

Return Value

An IDispatch pointer to a collection of QueryCategory objects.

Remarks

Call this member function to retrieve a pointer to the query’s collection of QueryCategory objects, which identify the Attribute objects, Dimension- Element objects, or function calls by which the query groups transactional data in the report.

Query::GetQueryItems

LPDISPATCH GetQueryItems();

Return Value

An IDispatch pointer to a collection of QueryItem objects.

Remarks

Call this member function to retrieve a pointer to the query’s collection of QueryItem objects, which identify the Measure objects or the function calls that specify the type of numeric data the query retrieves.

3-252 SDK for Snap-Ins Programmer’s Manual Query::GetSQL

Query::GetSQL

LPDISPATCH GetSQL();

Return Value

An IDispatch pointer to a ValueList object containing the SQL statement generated by the MetaCube engine.

Remarks

Call this member function to retrieve a pointer to the ValueList object containing the SQL statement generated by the MetaCube engine for any valid query. Each SQL statement represents a separate string in an array of values. For each different data source or comparison included in the query, MetaCube generates a separate SQL statement.

Query::GetTimeFiltered

BOOL GetTimeFiltered();

Return Value

A Boolean value. Nonzero indicates a query includes a ﬁlter on time; zero indicates the query does not include a ﬁlter on time.

Remarks

Call this member function to determine if a query includes a ﬁlter on time.

MetaCube Class Library 3-253 Query::OnAccuracyChanged

Query::OnAccuracyChanged

void OnAccuracyChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_accuracy() has changed.

Query::OnConﬁdenceChanged

void OnConfidenceChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_conﬁdence() has changed.

Query::OnDataSourceChanged

void OnDataSourceChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_dataSource() has changed.

3-254 SDK for Snap-Ins Programmer’s Manual Query::Retrieve

Query::Retrieve

void Retrieve();

Remarks

Call this member function to command MetaCube to transmit the SQL generated for the query directly to the relational database. Before it can execute, the query must consist of at least one QueryCategory object. If the query contains QueryCategory objects specifying attributes from different dimensions, the query must also include a QueryItem object. Several member functions of the MetaCube class of objects implicitly require query execution. If one of those member functions are called, it is not necessary to call Retrieve().

Query::Save

void Save();

Remarks

Call this member function to save the query deﬁnition that is currently stored in memory into the metadata tables in the relational database. The query is saved using the name and author speciﬁed by the member functions of the Query class of objects. Before calling this member function, SaveAs() must be called at least once to identify the folder where the query is saved.

MetaCube Class Library 3-255 Query::SaveAs

Query::SaveAs

void SaveAs( LPCTSTR Name, LPDISPATCH aFolder );

Parameters

Name The new name for the query. The existing name for the Query object is the name returned by Get_m_name().

aFolder The IDispatch pointer to the folder where you want to save the query. Two queries with the same name cannot be stored in the same folder.

Remarks

Call this member function to save the query deﬁnition currently stored in memory into the metadata tables in the relational database and assign the query a new name or store it in a different folder.

Query::SaveStorage

void SaveStorage( LPUNKNOWN Storage );

Parameters

Storage Points to a structured storage object where this Query object will be saved

Remarks

Call this member function to save a Query object in a structured storage object.

3-256 SDK for Snap-Ins Programmer’s Manual Query::SetItemOrientation

Query::SetItemOrientation

void SetItemOrientation( long nNewValue );

Parameters nNewValue A constant specifying a type of orientation

Remarks

Call this member function to set the orientation of measures returned by a query. Measures can be displayed as rows or columns. The metacons.h ﬁle assigns a constant to each possible type of orientation. The following table duplicates the orientation information listed in metacons.h:

Orientation Name in Metacons.h Constant

Rows OrientationRow 1

Columns OrientationColumn 2

Query::SetName

void SetName( LPCTSTR lpszNewValue );

Parameters lpszNewValue Points to the text string providing a new label for the Query object

Remarks

Call this member function to change the name of the Query object, which is initially speciﬁed as an argument when a Query object is instantiated.

MetaCube Class Library 3-257 Query::SetParameter

Query::SetParameter

void SetParameter( long index, LPCTSTR Value);

Parameters

index The 0-based index of the parameter stored in a ValueList object. The order of parameters depends on the order in which FilterElement objects were instantiated.

Value The values to be substituted for a parameter. These values should be listed in a single text string that conforms to SQL standards, listing multiple values within parentheses, placing each string value in single quotes, and demarcating values by commas, as in the following example: (‘Alden’, ‘Delmore’)

Remarks

Call this member function to assign a value or values to a filter parameter. Note that when submitting parameterized queries to QueryBack, undefined parameters must be stored in metadata for future reference by the UNIX process clientexec. To identify and define parameters in MetaCube’s metadata, launch MetaCube Agent Administrator. Parameters defined in MetaCube Agent Administrator and registered in MetaCube’s metadata take precedence over any parameter assignments made by calling SetParameter().

3-258 SDK for Snap-Ins Programmer’s Manual Query::SetSQL

Query::SetSQL

void SetSQL( long index, LPCTSTR Value);

Parameters index The 0-based index of an SQL statement in the ValueList object containing the SQL statements generated by the MetaCube engine for the query

Value A string containing the replacement SQL statement

Remarks

Call this member function to replace an SQL statement that was generated by the MetaCube engine for any valid query. For each different data source included in the query, MetaCube generates a separate SQL statement.

MetaCube Class Library 3-259 Query::Submit

Query::Submit

LPDISPATCH Submit(LPCTSTR Name, long Priority, const VARIANT FAR& TargetStartTime, long RecurType);

Return Value

An IDispatch pointer to a QueryBackJob object instantiated by this member function.

Parameters

Name The name assigned to the QueryBack object that this member function will instantiate

Priority A long integer representing the query’s priority. To assign a high priority, specify a high number. MetaCube Explorer limits priority values to a range of 1 to 5, but the SDK programming interface imposes no limits.

TargetStartTime A VARIANT type specifying when the server should process this query

RecurType A constant specifying the frequency with which a query should be executed. There are several options. The metacons.h ﬁle lists these options and assigns a constant to each. The following table duplicates the frequency options listed in metacons.h:

Frequency Name in Metacons.h Constant

Once RecurTypeNone 1 Daily RecurTypeDaily 2 Weekly RecurTypeWeekly 3 Monthly RecurTypeMonthly 4 Annually RecurTypeAnnually 5

Remarks

Call this member function to submit a query for background processing, which instantiates a QueryBackJob object. You cannot submit a query for background processing if any of the ﬁlters included in the query have not been saved.

3-260 SDK for Snap-Ins Programmer’s Manual QueryBackJob

QueryBackJob

CObject

CCmdTarget

COlapObject

QueryBackJob

Each QueryBackJob object describes the status of a query submitted for background processing. When a user submits a query for background processing, MetaCube places the query in a job queue. The SQL associated with the job is saved in metadata tables. The MetaCube engine assigns a number to the job and speciﬁes a job type, status, priority, and intended start time for the job. The queue stores this information. A simple algorithm determines when jobs run. The administrator sets a maximum number of concurrent jobs, and a server-side scheduling daemon runs jobs until either the maximum number of concurrent jobs is met or no more jobs require processing. If the user submits a job to be run immediately, MetaCube submits it with a target start time of now. If a user schedules a job to be run in the future, the scheduler runs the job at the designated time. The priority assigned to jobs determines the order in which concurrent jobs are run. To retrieve values for any QueryBack job, you must ﬁrst call the Refresh- Status() member function. This is necessary because of the nature of communication between the scheduling daemon on the server side and MetaCube on the client side. Both communicate through the Informix table that contains the job queue. Periodically, the server-side process automatically polls to see if any client-side processes have made changes to the queue (such as the submission of a new job). The client, on the other hand, does not automatically poll. MetaCube obtains information about the queue only when the RefreshStatus() member function is called, which directs MetaCube to poll the job table.

MetaCube Class Library 3-261 QueryBackJob Class Members

QueryBackJob Class Members

Operations

DeleteJob Deletes a job from the queue.

Get_m_iparent Identiﬁes the Metabase object that is the parent of a QueryBackJob object

GetErrorCode Retrieves an error code returned by the server while processing a QueryBack job

GetErrorText Retrieves an error message returned by the server while processing a QueryBack job

GetJobID Returns a job ID assigned to a QueryBack job by MetaCube when the job is submitted

GetName Retrieves the name of a QueryBack job, which corresponds to the original name of the Query object submitted for background processing

GetPriority Retrieves the priority assigned to a QueryBack job when it is submitted

GetRecurType Retrieves the frequency with which the scheduler re-executes a query

GetSize Retrieves the number of rows that a QueryBackJob object returns to the client

GetStartTime Retrieves the time at which the server began processing a QueryBack job

GetStatus Retrieves the status of a QueryBack job

GetStopTime Retrieves the time at which the server ﬁnished processing a QueryBack job

GetSubmitTime Retrieves the time at which at which a user submitted a job

3-262 SDK for Snap-Ins Programmer’s Manual QueryBackJob Class Members

Operations

GetTargetStart Retrieves the time at which a user requested that a QueryBack job begin processing

RefreshStatus Retrieves and refreshes the values of a Query- BackJob object

Retrieve Retrieves the results of a QueryBack job

MetaCube Class Library 3-263 QueryBackJob::DeleteJob

QueryBackJob::DeleteJob

void DeleteJob();

Remarks

Call this member function to delete a pending or completed job from the queue. This member function can also delete a job that is currently running. The job will be deleted when the status of the job changes to completed.

Deleting a recurring job that is pending prevents that job from spawning a new incarnation of itself for the following day, month, or year. When applied to a completed QueryBackJob object, this member function deletes whatever tables store the results of the job.

QueryBackJob::Get_m_iparent

class Metabase*& Get_m_iparent();

Return Value

A pointer to the Metabase object that is the parent of this QueryBackJob object.

Remarks

Call this member function to identify the Metabase object that is the parent of a QueryBackJob object.

3-264 SDK for Snap-Ins Programmer’s Manual QueryBackJob::GetErrorCode

QueryBackJob::GetErrorCode

long GetErrorCode();

Return Value

A long integer representing an error code. If there is no error, 0 is returned.

Remarks

Call this member function to retrieve the error code returned by the server while processing a QueryBack job.

QueryBackJob::GetErrorText

BSTR GetErrorText();

Return Value

An OLE string providing an error message returned by the server.

Remarks

Call this member function to retrieve the error message returned by the server while processing a QueryBack job.

MetaCube Class Library 3-265 QueryBackJob::GetJobID

QueryBackJob::GetJobID

long GetJobID();

Return Value

A long integer providing a job identiﬁcation number.

Remarks

Call this member function to retrieve the unique identiﬁcation number that the scheduling daemon assigns to each QueryBack job when it is submitted.

QueryBackJob::GetName

BSTR GetName();

Return Value

An OLE string providing the name of a QueryBack job.

Remarks

Call this member function to retrieve the name of a QueryBack job. The name returned corresponds to the name parameter provided for the Query::Submit() member function that initiated background processing of a query.

3-266 SDK for Snap-Ins Programmer’s Manual QueryBackJob::GetPriority

QueryBackJob::GetPriority

long GetPriority();

Return Value

A long integer representing the priority assigned to a job.

Remarks

Call this member function to retrieve the priority assigned to a QueryBack job when it is submitted.

MetaCube Class Library 3-267 QueryBackJob::GetRecurType

QueryBackJob::GetRecurType

long GetRecurType();

Return Value

A long integer representing the frequency with which the scheduler re- executes a query.

Remarks

Call this member function to retrieve the frequency with which the scheduler re-executes a query. Each recurrence of a query automatically creates a new QueryBack job. There are several options for the frequency with which a query can be re- executed. The metacons.h ﬁle lists these options and assigns a constant to each. The following table duplicates the frequency information listed in metacons.h:

Frequency Name in Metacons.h Constant

Once RecurTypeNone 1 (default value)

Daily RecurTypeDaily 2

Weekly RecurTypeWeekly 3

Monthly RecurTypeMonthly 4

Annually RecurTypeAnnually 5

3-268 SDK for Snap-Ins Programmer’s Manual QueryBackJob::GetSize

QueryBackJob::GetSize

long GetSize();

Return Value

A long integer providing the number of rows that a QueryBackJob object will return to the client. If the QueryBackJob object has not executed on the server, the value returned is zero.

Remarks

Call this member function to retrieve the number of rows that a Query- BackJob object returns to the client.

QueryBackJob::GetStartTime

VARIANT GetStartTime();

Return Value

A VARIANT that provides the time at which the server began processing a QueryBack job. Until the job starts, the value returned is null.

Remarks

Call this member function to retrieve the time at which the server began processing a QueryBack job.

MetaCube Class Library 3-269 QueryBackJob::GetStatus

QueryBackJob::GetStatus

long GetStatus();

Return Value

A long integer indicating whether a QueryBack job is pending, executing, or complete.

Remarks

Call this member function to retrieve the status of a QueryBack job. Jobs can be pending, executing, or complete. All jobs currently in the scheduler’s queue, which includes jobs scheduled to run at a later date, are classified as pending. The metacons.h file assigns a constant to each classification of a job’s status. The following table duplicates the job status information listed in metacons.h:

Job Status Name in Metacons.h Constant

Pending QueryBackJobStatusPending 0

Executing QueryBackJobStatusRunning 1

Completed QueryBackJobStatusFinished 2

3-270 SDK for Snap-Ins Programmer’s Manual QueryBackJob::GetStopTime

QueryBackJob::GetStopTime

VARIANT GetStopTime();

Return Value

A VARIANT that provides the time at which the server ﬁnished processing a QueryBack job.

Remarks

Call this member function to retrieve the time at which the server ﬁnished processing a QueryBack job.

QueryBackJob::GetSubmitTime

VARIANT GetSubmitTime();

Return Value

A VARIANT that provides the time at which a user submitted a job.

Remarks

Call this member function to retrieve the time at which a user submitted a job.

MetaCube Class Library 3-271 QueryBackJob::GetTargetStart

QueryBackJob::GetTargetStart

VARIANT GetTargetStart();

Return Value

A VARIANT that provides the time at which a user requested that a QueryBack job begin processing.

Remarks

Call this member function to determine the time at which a user requested that a QueryBack job begin processing, as speciﬁed in the parameters passed to Query::Submit(). Differences between the value returned by this member function and GetStartTime() result from the length of the job queue, the avail- ability of the scheduler daemon, the time between scheduler polls, and other factors.

QueryBackJob::RefreshStatus

void RefreshStatus();

Remarks

Call this member function to retrieve and refresh the values of a Query- BackJob object. Before calling any other QueryBackJob member function, you must call RefreshStatus().

3-272 SDK for Snap-Ins Programmer’s Manual QueryBackJob::Retrieve

QueryBackJob::Retrieve

LPDISPATCH Retrieve();

Return Value

The IDispatch pointer to the query holding the results of a QueryBack job.

Remarks

Call this member function to retrieve the results of a QueryBack job. This member function will return a pointer to a Query object. The MetaCubes collection of the Query object will be populated with MetaCube objects for which Get_m_scratch() returned FALSE prior to submitting the job for background processing.

MetaCube Class Library 3-273 QueryBackJobs

QueryBackJobs

CObject

CCmdTarget

COlapObject

COleCollection

QueryBackJobs

The QueryBackJobs class of objects manages collections of QueryBackJob objects. The QueryBackJobs class does not provide a member function that adds a QueryBackJob object. Query::Submit creates a QueryBackJob object. A Metabase object contains a collection of QueryBackJob objects. The Metabase object organizes its collection of QueryBackJob objects by user, showing only those jobs, both pending and complete, that have been submitted by a particular user. If a public user, such as “metapub,” creates a QueryBackJob object, other users can access that object.

QueryBackJobs Class Members

Operations

Get_m_iparent Identiﬁes the Metabase object that contains a collection of QueryBackJob objects

ItemJobID Identiﬁes a QueryBackJob object within a collection of QueryBackJob objects

RefreshStatus Retrieves and refreshes the values of all the QueryBackJob objects in a collection

3-274 SDK for Snap-Ins Programmer’s Manual QueryBackJobs::Get_m_iparent

QueryBackJobs::Get_m_iparent

class COlapObject*& Get_m_iparent();

Return Value

A pointer to the Metabase object that contains a collection of QueryBackJob objects.

Remarks

Use this member function to identify the Metabase object that contains a collection of QueryBackJob objects.

QueryBackJobs::RefreshStatus

void RefreshStatus();

Remarks

Call this member function to retrieve and refresh the values of all the Query- BackJob objects in a collection.

MetaCube Class Library 3-275 QueryBackJobs::ItemJobID

QueryBackJobs::ItemJobID

LPDISPATCH ItemJobID( long JobID );

Return Value

The IDispatch pointer to the QueryBackJob object.

Parameters

JobID The unique identiﬁcation number that the scheduling daemon assigns to each QueryBackJob object when the job is submitted. This number is the index into the QueryBackJobs collection.

Remarks

Call this member function to retrieve a QueryBackJob object within a collection of QueryBackJob objects.

3-276 SDK for Snap-Ins Programmer’s Manual QueryCategories

QueryCategories

CObject

CCmdTarget

COlapObject

COleCollection

QueryCategories

The QueryCategories class of objects manage collections of QueryCategory objects. The QueryCategories member functions allow you to add, remove, and rearrange objects within the collection.

MetaCube Class Library 3-277 QueryCategories Class Members

QueryCategories Class Members

Operations

Add Instantiates a new QueryCategory object, adds it to a collection of QueryCategory objects, and returns a pointer to that new object

Get_m_iparent Identiﬁes the Query object that contains a collection of QueryCategory objects

MakeFirst Rearranges the order of QueryCategory objects in a collection so a speciﬁed object becomes the ﬁrst item

MakeLast Rearranges the order of QueryCategory objects in a collection so a speciﬁed object becomes the last item

MakeNth Rearranges the order of QueryCategory objects in a collection so a speciﬁed object is moved to a designated position

Remove Removes a QueryCategory object from a collection of QueryCategory objects

Swap Swaps the position of two QueryCategory objects in a collection

3-278 SDK for Snap-Ins Programmer’s Manual QueryCategories::Add

QueryCategories::Add

LPDISPATCH Add( LPCTSTR Category );

Return Value

The IDispatch pointer associated with the QueryCategory object being instantiated.

Parameters

Category Pointer to the text string that is the name of an attribute or dimension element or the syntax of an expression to include in a query’s deﬁnition.

Remarks

Call this member function to instantiate a new QueryCategory object, which adds the new object to a collection of QueryCategory objects and returns a pointer to the new QueryCategory object. To avoid ambiguity when specifying the name of an object, follow the appropriate scoping rules, as described in the MetaCube Version 3.0 Technical Reference Manual.

MetaCube Class Library 3-279 QueryCategories::Get_m_iparent

QueryCategories::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the Query object that contains a collection of QueryCategory objects.

Remarks

Use this member function to identify the Query object that contains a collection of QueryCategory objects.

QueryCategories::MakeFirst

void MakeFirst( const VARIANT FAR& index );

Parameters

index A VARIANT representing the QueryCategory object to be moved within the collection of QueryCategory objects. The index constant can store an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of QueryCategory objects in a collection so a speciﬁed object becomes the ﬁrst item.

3-280 SDK for Snap-Ins Programmer’s Manual QueryCategories::MakeLast

QueryCategories::MakeLast

void MakeLast( const VARIANT FAR& index );

Parameters index A VARIANT representing the QueryCategory object to be moved within the collection of QueryCategory objects. The index constant can store an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of QueryCategory objects in a collection so a speciﬁed object becomes the last item.

QueryCategories::MakeNth

void MakeNth( const VARIANT FAR& index, long n );

Parameters index A constant representing the QueryCategory object to be moved within the collection of QueryCategory objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object). n A number specifying the new position for the QueryCat- egory object to be moved

Remarks

Call this member function to rearrange a collection of QueryCategory objects so a speciﬁed object can be moved to a designated position in the collection.

MetaCube Class Library 3-281 QueryCategories::Remove

QueryCategories::Remove

void Remove( const VARIANT FAR& index );

Parameters

index A constant representing the QueryCategory object to be removed from the collection of QueryCategory objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a QueryCategory object from a collection of QueryCategory objects.

3-282 SDK for Snap-Ins Programmer’s Manual QueryCategories::Swap

QueryCategories::Swap

void Swap( const VARIANT FAR& index1, const VARIANT FAR& index2 );

Parameters index1 A constant representing a QueryCategory object whose position will be swapped within the collection of QueryCat- egory objects. The index constant can be an integer (the 0- based index of the object) or a string (the name of the object). index2 An constant representing the other QueryCategory object whose position will be swapped. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to swap the position of two QueryCategory objects in a collection of QueryCategory objects.

MetaCube Class Library 3-283 QueryCategory

QueryCategory

CObject

CCmdTarget

COlapObject

QueryCategory

A QueryCategory object speciﬁes one of the following to include in a query’s deﬁnition:

■ An Attribute object—describes the physical columns in the relational database that store string values by which transactional data is characterized and grouped ■ A DimensionElement object—identiﬁes a column in the relational database that deﬁnes a particular level in a dimensional hierarchy. This column typically stores a unique code for each value and can join to fact or summary tables. ■ A function call—instructs MetaCube to use an extension to perform complex calculations

3-284 SDK for Snap-Ins Programmer’s Manual QueryCategory Class Members

QueryCategory Class Members

Operations

Get_m_category Retrieves a pointer to a string that provides the QueryCat- egory expression, which deﬁnes grouping within a query. The string can specify the name of an Attribute or Dimen- sionElement object or a function call.

Get_m_extension Retrieves a pointer to a CIExtension object if a QueryCat- egory object needs to invoke an extension

Get_m_iparent Identiﬁes the parent of this QueryCategory object

Get_m_name Retrieves a pointer to the string containing the label of the QueryCategory object

Get_m_object Retrieves a pointer to the Attribute or DimensionElement object on which a QueryCategory expression is based

Get_m_orientation Retrieves a reference to a constant that determines whether values returned by the QueryCategory object are displayed in rows, columns, or pages

Get_m_parse Retrieves a reference to a CParseNode object, which describes in detail the operations MetaCube must perform to process the string returned by Get_m_category().

Get_m_parsed Indicates whether a QueryCategory object has been parsed

Get_m_sortDirection Retrieves a constant that determines how attribute values will be sorted

Get_m_type Classiﬁes the QueryCategory expression as an Attribute object, a DimensionElement object, or a function call

GetName Retrieves an OLE string containing the label of the Query- Category object

GetObject Retrieves an IDispatch pointer to the Attribute or Dimen- sionElement object on which a QueryCategory expression is based

MetaCube Class Library 3-285 QueryCategory Class Members

Operations

OnCategoryChanged Issues a notiﬁcation that the value referenced by Get_m_category() has changed

OnOrientationChanged Issues a notiﬁcation that the value referenced by Get_m_orientation() has changed

OnSortDirectionChanged Issues a notiﬁcation that the value referenced by Get_m_sortDirection() has changed

SetName Changes the label of the QueryCategory object

3-286 SDK for Snap-Ins Programmer’s Manual QueryCategory::Get_m_category

QueryCategory::Get_m_category

CString& Get_m_category();

Return Value

A reference to the string containing the name of the object or the syntax of the expression that deﬁnes grouping within a query.

Remarks

Set the value returned by this member function to provide the QueryCat- egory expression, which deﬁnes grouping within a query. This member function can return the name of an Attribute or DimensionElement object or a function call. Changing the value returned by this member function alters the grouping of the query that was originally speciﬁed when the QueryCat- egory object was instantiated. When you change the value returned by this function, you should call OnCategoryChanged().

MetaCube Class Library 3-287 QueryCategory::Get_m_extension

QueryCategory::Get_m_extension

class CIExtension*& Get_m_extension();

Return Value

A reference to a CIExtension object. If a QueryCategory object does not need to invoke an extension, MetaCube returns a null value when this member function is called.

Remarks

This member function retrieves a pointer to a CIExtension object when a QueryCategory object needs to invoke an extension. MetaCube determines what extension is necessary, if any, by processing the string returned by Get_m_category().

QueryCategory::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the Query object that is the parent of this QueryCategory object.

Remarks

Use this member function to identify the object that is the parent of this QueryCategory object.

3-288 SDK for Snap-Ins Programmer’s Manual QueryCategory::Get_m_name

QueryCategory::Get_m_name

CString& Get_m_name();

Return Value

A reference to the string containing the label identifying the QueryCategory object. Until a new label has been assigned to the QueryCategory object, the value returned is the same as the string returned by Get_m_category().

Remarks

Call this member function to retrieve the string containing the label of the QueryCategory object. To change a label for a QueryCategory object, use the SetName() member function.

QueryCategory::Get_m_object

class COlapObject*& Get_m_object();

Return Value

A pointer to the object on which a QueryCategory expression is based. A null value is returned for expressions based on multiple Attribute or Dimension- Element objects, such as a comparison.

Remarks

Call this member function retrieve a pointer to the Attribute or Dimension- Element object on which a QueryCategory expression is based. When a QueryCategory object represents a bucket or some other expression, this member function returns a pointer to the Attribute or DimensionElement object referred to by the syntax of that expression. MetaCube determines what Attribute or DimensionElement object is necessary for a QueryCat- egory object by processing the string returned by Get_m_category().

MetaCube Class Library 3-289 QueryCategory::Get_m_orientation

QueryCategory::Get_m_orientation

long& Get_m_orientation();

Return Value

A reference to a constant that determines how values returned by the Query- Category object are displayed.

Remarks

Set the value returned by this member function to determine whether values returned by the QueryCategory object are displayed in separate rows, columns, or pages. By default, MetaCube displays values in the row orientation. The metacons.h ﬁle assigns a constant to each possible type of orientation. The following table duplicates the orientation information listed in metacons.h:

Orientation Name in Metacons.h Constant

Rows OrientationRow 1

Columns OrientationColumn 2

Pages OrientationPage 3

Changing the value returned by this member function ultimately requires that a new MetaCube object be created, but it does not require the analysis engine to submit another query to the database. When you change the value returned by this function, you should call OnOrientationChanged().

3-290 SDK for Snap-Ins Programmer’s Manual QueryCategory::Get_m_parse

QueryCategory::Get_m_parse

class CParseNode*& Get_m_parse();

Return Value

A reference to a CParseNode object. If a QueryCategory object has not been parsed, null is returned.

Remarks

Call this member function to identify the CParseNode object created for a QueryCategory object. The CParseNode object describes in detail what operations MetaCube must take to process the string returned by Get_m_category(). The member functions Get_m_extension() and Get_m_object() identify the objects that will perform the operations speciﬁed by the CParseNode object.

QueryCategory::Get_m_parsed

BOOL& Get_m_parsed();

Return Value

A Boolean value. Nonzero indicates the string returned by Get_m_category() has been parsed. Zero indicates the string has not been parsed.

Remarks

Call this member function to determine if the string returned by Get_m_category() has been parsed.

MetaCube Class Library 3-291 QueryCategory::Get_m_sortDirection

QueryCategory::Get_m_sortDirection

long& Get_m_sortDirection();

Return Value

A reference to a constant that determines how values returned by the Query- Category object are sorted.

Remarks

Set the value returned by this member function to determine how values returned by the QueryCategory object are sorted. The metacons.h ﬁle deﬁnes possible sorting methods and assigns a constant to each method. The following table duplicates the sorting information listed in metacons.h:

Sort Direction Name in Metacons.h Constant

No Sort SortDirectionIgnore 0

Ascending Order SortDirectionAsc 1 (default value)

Descending Order SortDirectionDesc 2

The member functions MetaCube::Get_m_sortColumns() and MetaCube::Get_m_sortRows(), which sort columns or rows on the basis of a measure’s values, override conﬂicting sorts speciﬁed by this member function. When you change the value returned by this function, you should call OnSortDirectionChanged().

3-292 SDK for Snap-Ins Programmer’s Manual QueryCategory::Get_m_type

QueryCategory::Get_m_type

enum QueryCatType& Get_m_type();

Return Value

A reference to the QueryCatType enumerated type. The possible Query- CatType values are AttributeType, DimensionElementType, or FunctionType.

Remarks

This member function flags the QueryCategory expression as an Attribute object, a DimensionElement object, or a function call. MetaCube uses this flag to process the string returned by Get_m_category(). If the flag returned by Get_m_type() indicates an Attribute or DimensionElement object, Get_m_object() specifies the appropriate object used to process the Query- Category expression. If the flag specifies a function call, Get_m_extension() specifies the extension that is appropriate for processing the QueryCategory expression.

QueryCategory::GetName

BSTR GetName();

Return Value

An OLE string containing the label identifying the QueryCategory object. Until a new label has been assigned to the QueryCategory object, this member function returns the same string as Get_m_category().

Remarks

Call this member function to retrieve an OLE string containing the label of a QueryCategory object. To change a label for a QueryCategory object, use the SetName() member function.

MetaCube Class Library 3-293 QueryCategory::GetObject

QueryCategory::GetObject

LPDISPATCH GetObject();

Return Value

A IDispatch pointer to the object on which a QueryCategory expression is based. A null value is returned for expressions based on multiple Attribute or DimensionElement objects, such as a comparison.

Remarks

Call this member function to retrieve a pointer to the Attribute or Dimension- Element object on which a QueryCategory expression is based. When a QueryCategory object represents a bucket or some other expression, this member function returns a pointer to the Attribute or DimensionElement object referred to by the syntax of that expression.

QueryCategory::OnCategoryChanged

void OnCategoryChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_category() has changed.

3-294 SDK for Snap-Ins Programmer’s Manual QueryCategory::OnOrientationChanged

QueryCategory::OnOrientationChanged

void OnOrientationChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_orientation() has changed.

QueryCategory::OnSortDirectionChanged

void OnSortDirectionChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_sortDirection() has changed.

MetaCube Class Library 3-295 QueryCategory::SetName

QueryCategory::SetName

void SetName( LPCTSTR lpszNewValue );

Parameters

lpszNewValue Points to the text string providing a new label for the Query- Category object

Remarks

Call this member function to change the label of the QueryCategory object. Calling this member function leaves the grouping of the query unaltered but changes the label MetaCube returns when displaying QueryCategory values. Note that this member function differs from the MetaCube bucket function, which groups and labels the values of the QueryCategory object rather than the QueryCategory object itself.

3-296 SDK for Snap-Ins Programmer’s Manual QueryItem

QueryItem

CObject

CCmdTarget

COlapObject

QueryItem

A QueryItem object speciﬁes a Measure object or a function call to include in a query’s deﬁnition. Measure objects represent numeric data, such as the number of units sold or gross revenue. A function call instructs MetaCube to use an extension to perform complex calculations.

MetaCube Class Library 3-297 QueryItem Class Members

QueryItem Class Members

Operations

Get_m_extensions Retrieves a list of all the registered extensions that will be called by the QueryItem object

Get_m_formatString Retrieves a string that contains the syntax used for formatting numeric data in different display environments

Get_m_iparent Identiﬁes the Query object that is the parent of this QueryItem object

Get_m_item Retrieves the name of a Measure object or the syntax of a function call that deﬁnes a QueryItem

Get_m_name Retrieves a pointer to the string containing the label displayed in a report as the name of a QueryItem

Get_m_object Retrieves a pointer to the Measure object on which a QueryItem expression is based

Get_m_parse Retrieves a reference to a CParseNode object, which describes in detail the operations MetaCube must perform to process the string returned by Get_m_item().

Get_m_parsed Indicates whether a QueryItem object has been parsed

Get_m_type Classiﬁes the QueryItem expression as a Measure object or a function call

GetFormatString Retrieves a string that contains the syntax used for formatting numeric data in different display environments

GetItem Retrieves the name of a Measure object or the syntax of a complex function call that deﬁnes a QueryItem

GetName Retrieves an OLE string containing the label of the QueryItem displayed in a report

GetObject Retrieves an IDispatch pointer to the Measure object on which a QueryItem expression is based

3-298 SDK for Snap-Ins Programmer’s Manual QueryItem Class Members

Operations

SetFormatString Deﬁnes new syntax used for formatting numeric data in different display environments

SetItem Changes the name of a Measure object or the syntax of a complex function call that deﬁnes a QueryItem

SetName Changes the label of the QueryItem displayed in a report

MetaCube Class Library 3-299 QueryItem::Get_m_extensions

QueryItem::Get_m_extensions

IExtensionArray& Get_m_extensions();

Return Value

A reference to an array that lists all of the registered extensions that will be called to process a function.

Remarks

Call this member function to retrieve a list of all the registered extensions that will be called if a QueryItem object needs to invoke one or more extensions. MetaCube determines what extensions are necessary by processing the string returned by Get_m_item().

3-300 SDK for Snap-Ins Programmer’s Manual QueryItem::Get_m_formatString

QueryItem::Get_m_formatString

CString& Get_m_formatString();

Return Value

A reference to a string that stores the syntax for a measure’s formatting.

Remarks

Call this member function to retrieve a string that contains the syntax used for formatting numeric data in different display environments, such as in an Excel Spreadsheet or a reporting control. The syntax returned by this member function deﬁnes the formatting for a measure as it will be displayed for a particular query. The MetaCube engine stores the formatting information provided by Get_m_formatString(), but MetaCube does not interpret or process that information. Ultimately, an object control or an application will format measure data, interpreting the formatting syntax stored by MetaCube. The syntax of the string returned by Get_m_formatString() will vary depending on the formatting information required by the object control or application. Use the SetFormatString() member function to change the format string for a QueryItem object. If the QueryItem object’s format string is left empty, the format string for the measure is used to format the measure’s numeric data.

MetaCube Class Library 3-301 QueryItem::Get_m_iparent

QueryItem::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the Query object that is the parent of this QueryItem object.

Remarks

Use this member function to identify the Query object that is the parent of this QueryItem object.

QueryItem::Get_m_item

CString& Get_m_item();

Return Value

A reference to the string containing either the name of the measure or the actual syntax of the expression that deﬁnes a QueryItem.

Remarks

Call this member function to retrieve the name of a Measure object or the syntax of a function call that deﬁnes a QueryItem. Use the SetItem() member function to change the value returned by this member function.

3-302 SDK for Snap-Ins Programmer’s Manual QueryItem::Get_m_name

QueryItem::Get_m_name

CString& Get_m_name();

Return Value

A reference to the string containing the label that is displayed in a report as the name of a QueryItem. Until a new label has been assigned to an object, the value returned is the same as the string returned by Get_m_item().

Remarks

Call this member function to retrieve a reference to the string containing the label that is displayed in a report as the name of a QueryItem. To change a label for a QueryItem, use the SetName() member function.

QueryItem::Get_m_object

class Measure*& Get_m_object();

Return Value

A reference to the Measure object on which a QueryItem expression is based. A null value is returned for expressions based on multiple Measure objects.

Remarks

Call this member function to retrieve a reference to the Measure object on which a QueryItem expression is based. When a QueryItem object represents an expression, such as a moving average, this member function returns a pointer to the Measure object referred to by the syntax of that expression. In either case, MetaCube determines what Measure object should be returned by processing the string returned by Get_m_item().

MetaCube Class Library 3-303 QueryItem::Get_m_parse

QueryItem::Get_m_parse

class CParseNode*& Get_m_parse();

Return Value

A reference to a CParseNode object. If a QueryItem object has not been parsed, null is returned.

Remarks

Call this member function to retrieve a reference to a CParseNode object created for a QueryItem object. The CParseNode object describes in detail what operations MetaCube must perform to process the string returned by Get_m_item(). The member functions Get_m_extensions() and Get_m_object() identify the objects that will perform the operations speciﬁed by the CParseNode object.

QueryItem::Get_m_parsed

BOOL& Get_m_parsed();

Return Value

A Boolean value. Nonzero indicates the string returned by Get_m_item() has been parsed. Zero indicates the string has not been parsed.

Remarks

Call this member function to determine if the string returned by Get_m_item() has been parsed.

3-304 SDK for Snap-Ins Programmer’s Manual QueryItem::Get_m_type

QueryItem::Get_m_type

enum QueryItemType& Get_m_type();

Return Value

A reference to the QueryItemType enumerated type. The possible Query- ItemType values are MeasureType or FunctionType.

Remarks

This member function references a flag that classifies the QueryItem expression as a Measure object or a function call. MetaCube uses this flag to process the string returned by Get_m_item(). If Get_m_type() flags a Measure object, Get_m_object() specifies the appropriate object used to process the QueryItem expression. If Get_m_type() flags a function call, Get_m_extensions() specifies the extension or multiple extensions necessary for processing the QueryItem expression.

MetaCube Class Library 3-305 QueryItem::GetFormatString

QueryItem::GetFormatString

BSTR GetFormatString();

Return Value

An OLE string that stores the syntax for a measure’s formatting.

Remarks

3-306 SDK for Snap-Ins Programmer’s Manual QueryItem::GetItem

QueryItem::GetItem

BSTR GetItem();

Return Value

An OLE string containing either the name of the measure or the syntax of the expression that deﬁnes a QueryItem.

Remarks

Call this member function to retrieve the name of a Measure object or the syntax of a complex function call that deﬁnes a QueryItem. Use the SetItem() member function to change the value returned by this member function.

QueryItem::GetName

BSTR GetName();

Return Value

An OLE string containing the label displayed in a report as the name of a QueryItem. Until a new label has been assigned, the value returned is the same as the string returned by GetItem().

Remarks

Call this member function to retrieve the string containing the label that is displayed in a report as the name of a QueryItem. To change a label for a QueryItem, use the SetName() member function.

MetaCube Class Library 3-307 QueryItem::GetObject

QueryItem::GetObject

LPDISPATCH GetObject();

Return Value

An IDispatch pointer to the Measure object on which a QueryItem expression is based. A null value is returned for expressions based on multiple Measure objects.

Remarks

This member function retrieves a pointer to the Measure object on which a QueryItem expression is based. When a QueryItem object represents an expression, such as a moving average, this member function returns a pointer to the Measure object referred to by the syntax of that expression. In either case, MetaCube determines what Measure object should be returned by processing the string returned by Get_m_item().

3-308 SDK for Snap-Ins Programmer’s Manual QueryItem::SetFormatString

QueryItem::SetFormatString

void SetFormatString( LPCTSTR lpszNewValue );

Parameters lpszNewValue Points to the text string providing new syntax for a measure’s formatting. If the QueryItem object’s format string is left empty, the format string for the measure is used to format the measure’s numeric data.

Remarks

Call this member function to deﬁne new syntax used for formatting numeric data in different display environments, such as in an Excel Spreadsheet or a reporting control. This syntax deﬁnes the formatting for a measure as it will be displayed for a particular query. A value for Get_m_formatString() can be set before running a query. Alternatively, the MetaCube::GetFormatStrings() member function returns a ValueList object that provides formatting syntax for all measures reported in a query. That ValueList object provides a single, convenient source of all formatting syntax for the application or report control.

MetaCube Class Library 3-309 QueryItem::SetItem

QueryItem::SetItem

void SetItem( LPCTSTR lpszNewValue );

Parameters

lpszNewValue Points to the text string providing a new name for a Measure object or the new syntax for a function call

Remarks

Call this member function to change the Measure object or the syntax of a function call that deﬁnes a QueryItem. Changing the value of the parameter passed to this member function alters the numeric data retrieved by the query, as was originally speciﬁed when the QueryItem object was instantiated.

QueryItem::SetName

void SetName( LPCTSTR lpszNewValue );

Parameters

lpszNewValue Points to the text string providing a new label that will be displayed in a report as the name of a QueryItem

Remarks

Call this member function to change the label displayed in a report as the name of a QueryItem. Changing this value leaves the numeric data of a query unaltered.

3-310 SDK for Snap-Ins Programmer’s Manual QueryItems

QueryItems

CObject

CCmdTarget

COlapObject

COleCollection

QueryItems

The QueryItems class of objects manage collections of QueryItem objects. The QueryItems member functions allow you to add, remove, rearrange QueryItem objects.

MetaCube Class Library 3-311 QueryItems Class Members

QueryItems Class Members

Operations

Add Instantiates a new QueryItem object, adds the object to a collection of QueryItem objects, and returns a pointer to that new object

Get_m_iparent Identiﬁes the Query object that contains a collection of QueryItem objects

MakeFirst Rearranges the order of QueryItem objects in a collection so a speciﬁed object becomes the ﬁrst item

MakeLast Rearranges the order of QueryItem objects in a collection so a speciﬁed object becomes the last item

MakeNth Rearranges the order of QueryItem objects in a collection so a speciﬁed object is moved to a designated position

Remove Removes a QueryItem object from a collection of QueryItem objects

Swap Swaps the position of two QueryItem objects in a collection

3-312 SDK for Snap-Ins Programmer’s Manual QueryItems::Add

QueryItems::Add

LPDISPATCH Add( LPCTSTR Measure );

Return Value

The IDispatch pointer associated with the QueryItem object being instantiated.

Parameters

Category Pointer to the text string that is the name of the measure or the syntax of a function call to include in a query’s deﬁnition.

Remarks

Call this member function to instantiate a new QueryItem object, which adds the new object to a collection of QueryItem objects and returns a pointer to the new QueryItem object.

QueryItems::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the Query object that contains a collection of QueryItem objects.

Remarks

Use this member function to identify the Query object that contains a collection of QueryItem objects.

MetaCube Class Library 3-313 QueryItems::MakeFirst

QueryItems::MakeFirst

void MakeFirst( const VARIANT FAR& index );

Parameters

index A constant representing the QueryItem object to be moved within the collection of QueryItem objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of QueryItem objects in a collection so the speciﬁed object becomes the ﬁrst item.

QueryItems::MakeLast

void MakeLast( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of QueryItem objects in a collection so the speciﬁed object becomes the last item.

3-314 SDK for Snap-Ins Programmer’s Manual QueryItems::MakeNth

QueryItems::MakeNth

void MakeNth( const VARIANT FAR& index, long n );

Parameters index A constant representing the QueryItem object to be moved within the collection of QueryItem objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object). n A number specifying the new position for the QueryItem object to be moved.

Remarks

Call this member function to rearrange a collection of QueryItem objects so the speciﬁed object can be moved to a designated position in the collection.

QueryItems::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the QueryItem object to be removed from the collection of QueryItem objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a QueryItem object from a collection of QueryItem objects.

MetaCube Class Library 3-315 QueryItems::Swap

QueryItems::Swap

void Swap( const VARIANT FAR& index1, const VARIANT FAR& index2 );

Parameters

index1 A constant representing the QueryItem object whose position will be swapped within the collection of QueryItem objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

index2 An index representing the other QueryItem object to be swapped. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to swap the position of two QueryItem objects in a collection of QueryItem objects.

3-316 SDK for Snap-Ins Programmer’s Manual Summaries

Summaries

CObject

CCmdTarget

COlapObject

COleCollection

Summaries

The Summaries class of objects manage collections of Summary objects. A Summary object performs calculations on groupings within a report. The Summaries member functions allow you to add new Summary objects to the collection, remove Summary objects, and rearrange the position of the Summary objects within the collection.

MetaCube Class Library 3-317 Summaries Class Members

Summaries Class Members

Operations

Add Instantiates a new Summary object, adds it to a collection of Summary objects, and returns a pointer to that new object

Get_m_iparent Identiﬁes the MetaCube object that contains a collection of Summary objects

MakeFirst Rearranges the order of Summary objects in a collection so a speciﬁed object becomes the ﬁrst item

MakeLast Rearranges the order of Summary objects in a collection so a speciﬁed object becomes the last item

MakeNth Rearranges the order of Summary objects in a collection so a speciﬁed object is moved to a designated position

Remove Removes a Summary object from a collection of Summary objects

Swap Swaps the position of two Summary objects in a collection

3-318 SDK for Snap-Ins Programmer’s Manual Summaries::Add

Summaries::Add

LPDISPATCH Add( LPDISPATCH QueryCategory, long SummaryType );

Return Value

The IDispatch pointer associated with the Summary object being created.

Parameters

QueryCategory IDispatch pointer to the QueryCategory object that deﬁnes a grouping within a report. All sub-rows within the grouping will be summed, averaged, or counted. If the value passed in for SummaryType parameter speciﬁes a “Grand” summary, such as a GrandTotal or a GrandAverage, pass in a null value for QueryCategory.

SummaryType A long integer representing the type of calculation to perform

Remarks

Call this member function to instantiate a new Summary object, which adds the new object to the collection of Summary objects and returns a pointer to the new Summary object. The new Summary object will perform a summarization on the sub-rows within the report grouping speciﬁed by the QueryCategory object. The type of calculation to be performed is determined by the SummaryType argument. The metacons.h ﬁle assigns a constant to each possible type of summarization. The following table duplicates the summarization information listed in metacons.h:

Type of Summarization Name in Metacons.h Constant

Subtotal SummaryTotal 1

Average SummaryAverage 2

Count SummaryCount 3

Minimum SummaryMin 4

Maximum SummaryMax 5

MetaCube Class Library 3-319 Summaries::Add

Grand Total, All Rows SummaryRowGrandTotal 11

Average, All Rows SummaryRowGrandAverage 12

Count, All Rows SummaryRowGrandCount 13

Minimum Value, Among All SummaryRowGrandMin 14 Rows

Maximum Value, Among All SummaryRowGrandMax 15 Rows

Grand Total, All Columns SummaryColumnGrandTotal 21

Average, All Columns SummaryColumnGrandAverage 22

Count, All Columns SummaryColumnGrandCount 23

Minimum Value, Among All SummaryColumnGrandMin 24 Columns

Maximum Value, Among All SummaryColumnGrandMax 25 Columns

3-320 SDK for Snap-Ins Programmer’s Manual Summaries::Get_m_iparent

Summaries::Get_m_iparent

class MetaCube*& Get_m_iparent();

Return Value

A pointer to the MetaCube object that contains a collection of Summary objects.

Remarks

Use this member function to identify the MetaCube object that contains a collection of Summary objects.

Summaries::MakeFirst

void MakeFirst( const VARIANT FAR& index );

Parameters index A constant representing the Summary object to be moved within the collection of Summary objects. The constant must ben an integer (the 0-based index of the object).

Remarks

Call this member function to rearrange the order of Summary objects in a collection so the speciﬁed object becomes the ﬁrst item.

MetaCube Class Library 3-321 Summaries::MakeLast

Summaries::MakeLast

void MakeLast( const VARIANT FAR& index );

Parameters

index A constant representing the Summary object to be moved within the collection of Summary objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to rearrange the order of Summary objects in a collection so the speciﬁed object becomes the last item.

Summaries::MakeNth

void MakeNth( const VARIANT FAR& index, long n );

Parameters

n A number specifying the new position for the Summary object to be moved.

Remarks

Call this member function to rearrange a collection of Summary objects so the speciﬁed object can be moved to a designated position in the collection.

3-322 SDK for Snap-Ins Programmer’s Manual Summaries::Remove

Summaries::Remove

void Remove( const VARIANT FAR& index );

Parameters index A constant representing the Summary object to be removed from the collection of Summary objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to remove a Summary object from a collection of Summary objects.

Summaries::Swap

void Swap( const VARIANT FAR& index1, const VARIANT FAR& index2 );

Parameters index1 A constant representing the Summary object whose position will be swapped within the collection of Summary objects. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object). index2 An index representing the other Summary object to be swapped. The index constant can be an integer (the 0-based index of the object) or a string (the name of the object).

Remarks

Call this member function to swap the position of two Summary objects in a collection of Summary objects.

MetaCube Class Library 3-323 Summary

Summary

CObject

CCmdTarget

COlapObject

Summary

A Summary object performs calculations on groupings within a query. Many types of calculation can be performed, including sums, averages, counts, minimums, and maximums. Values within a query are grouped by specifying a QueryCategory object.

3-324 SDK for Snap-Ins Programmer’s Manual Summary Class Members

Summary Class Members

Operations

Get_m_iparent Identiﬁes the MetaCube object that is the parent of this Summary object

Get_m_queryCategory Identiﬁes the QueryCategory object that deﬁnes grouping within a query

Get_m_summaryType Identiﬁes the type of calculation performed on all sub- rows within the grouping speciﬁed by the QueryCat- egory object used for this Summary object

GetQueryCategory Retrieves a pointer to the QueryCategory object that deﬁnes grouping within a query

OnSummaryTypeChanged Issues a notiﬁcation that the value referenced by Get_m_summaryType() has changed

SetQueryCategory Changes the QueryCategory object that deﬁnes grouping within a query. A calculation is performed on all sub-rows within that grouping.

MetaCube Class Library 3-325 Summary::Get_m_iparent

Summary::Get_m_iparent

class Query*& Get_m_iparent();

Return Value

A pointer to the MetaCube object that is the parent of this Summary object.

Remarks

Use this member function to identify the parent of this Summary object.

Summary::Get_m_queryCategory

LPDISPATCH& Get_m_queryCategory();

Return Value

A reference to the IDispatch pointer to the QueryCategory object that deﬁnes grouping within a query. Null is referenced if a Summary object performs a “Grand” summary, such as a GrandTotal or a GrandAverage.

Remarks

Call this member function to retrieve a reference to the QueryCategory object that deﬁnes grouping within a query. A calculation is performed on all sub- rows within that grouping. To determine what type of calculation is performed, call Get_m_summaryType(). To deﬁne a new QueryCategory object for this Summary object, call SetQueryCategory().

3-326 SDK for Snap-Ins Programmer’s Manual Summary::Get_m_summaryType

Summary::Get_m_summaryType

long& Get_m_summaryType();

Return Value

A reference to a long integer specifying a type of calculation to be performed.

Remarks

Set the value returned by this member function to determine what type of calculation is performed on all sub-rows within the grouping speciﬁed by the QueryCategory object. The metacons.h ﬁle assigns a constant to each possible type of summarization. The following table duplicates the summarization information listed in metacons.h:

Type of Summarization Name in Metacons.h Constant

Subtotal SummaryTotal 1

Average SummaryAverage 2

Count SummaryCount 3

Minimum SummaryMin 4

Maximum SummaryMax 5

Grand Total, All Rows SummaryRowGrandTotal 11

Average, All Rows SummaryRowGrandAverage 12

Count, All Rows SummaryRowGrandCount 13

Minimum Value, Among All SummaryRowGrandMin 14 Rows

Maximum Value, Among All SummaryRowGrandMax 15 Rows

Grand Total, All Columns SummaryColumnGrandTotal 21

Average, All Columns SummaryColumnGrandAverage 22

MetaCube Class Library 3-327 Summary::GetQueryCategory

Count, All Columns SummaryColumnGrandCount 23

Minimum Value, Among All SummaryColumnGrandMin 24 Columns

Maximum Value, Among All SummaryColumnGrandMax 25 Columns

When you change the value referenced by Get_m_summaryType(), you should call OnSummaryTypeChanged().

Summary::GetQueryCategory

LPDISPATCH GetQueryCategory();

Return Value

An IDispatch pointer to the QueryCategory object that deﬁnes grouping within a query report.

Remarks

Call this member function to retrieve a pointer to the QueryCategory object that deﬁnes grouping within a query. A calculation is performed on all sub- rows within that grouping. To determine what type of calculation is performed, call Get_m_summaryType(). To deﬁne a new QueryCategory object for this Summary object, call SetQueryCategory().

3-328 SDK for Snap-Ins Programmer’s Manual Summary::OnSummaryTypeChanged

Summary::OnSummaryTypeChanged

void OnSummaryTypeChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value referenced by Get_m_summaryType() has changed.

Summary::SetQueryCategory

void SetQueryCategory( LPDISPATCH newValue );

Parameters newValue IDispatch pointer to a new QueryCategory object that deﬁnes a grouping within a query. A calculation will be performed on all sub-rows within the grouping.

Remarks

Call this member function to change the QueryCategory object that deﬁnes grouping within a query. A calculation is performed on all sub-rows within the speciﬁed grouping. To determine what type of calculation is performed, call Get_m_summaryType().

MetaCube Class Library 3-329 ValueList

ValueList

CObject

CCmdTarget

COlapObject

ValueList

Objects of the ValueList class embody lists of values created by some of MetaCube’s objects. Using the ValueList member functions, you can translate data in a ValueList object into an array or a tab-delimited string. The ValueList data members allow you to select a subset of the values in the ValueList object, choose the maximum number of values to return, and specify how values are sorted when they are returned.

3-330 SDK for Snap-Ins Programmer’s Manual ValueList Class Members

ValueList Class Members

Operations

Get_m_iparent Identiﬁes the object that contains a ValueList object

Get_m_maxRows Speciﬁes a maximum number of values that can be returned from a ValueList object

Get_m_sort Speciﬁes a method of sorting for the values returned from a ValueList object

Get_m_subset Speciﬁes SQL wildcard syntax, which can be used to deﬁne a subset of the contents of a ValueList object

GetArrayValues Translates the contents of a ValueList object into an OLE SafeArray

GetTabbedValues Translates the contents of a ValueList object into a tab-delimited string

OnMaxRowsChanged Issues a notiﬁcation that the value returned by Get_m_maxRows() has changed

OnSortChanged Issues a notiﬁcation that the value returned by Get_m_sort() has changed

OnSubsetChanged Issues a notiﬁcation that the value returned by Get_m_subset() has changed

MetaCube Class Library 3-331 ValueList::Get_m_iparent

ValueList::Get_m_iparent

class COlapObject*& Get_m_iparent();

Return Value

A reference to a pointer to the object that contains a ValueList object.

Remarks

Use this member function to identify the object that is the parent of a ValueList object.

ValueList::Get_m_maxRows

long& Get_m_maxRows();

Return Value

A reference to a long integer indicating the maximum number of values that can be returned from a ValueList object.

Remarks

Set the value returned by this member function to specify a maximum number of values that can be returned from a ValueList object. Setting a maximum in this way is especially useful for preventing a tab-delimited string derived from a ValueList object from becoming unwieldy. The default value returned by Get_m_maxRows() is 200. You can use this data member to limit only a ValueList object that is contained by an Attribute object. When you change the value returned by this member function, you should call OnMaxRowsChanged().

3-332 SDK for Snap-Ins Programmer’s Manual ValueList::Get_m_sort

ValueList::Get_m_sort

long& Get_m_sort();

Return Value

A reference to a long integer that determines a sorting method for the values returned from a ValueList object.

Remarks

Set the value returned by this member function to specify a sorting method for the values returned from a ValueList object. The metacons.h ﬁle deﬁnes possible sorting methods and assigns a constant to each method. The following table duplicates the sorting information listed in metacons.h:

Sort Direction Name in Metacons.h Constant

No Sort SortDirectionIgnore 0

Ascending Order SortDirectionAsc 1

Descending Order SortDirectionDesc 2

You can use this member function to determine the sorting direction of only a ValueList object that is contained by an Attribute object. When you change the value returned by this member function, you should call OnSortChanged().

MetaCube Class Library 3-333 ValueList::Get_m_subset

ValueList::Get_m_subset

CString& Get_m_subset();

Return Value

A reference to a string specifying SQL wildcard syntax.

Remarks

Set the value returned by this member function to specify SQL wildcard syntax. Because the wildcard character is appended to the end of any string referenced by this member function, you can use this member function to retrieve a subset of the contents of a ValueList object based on the leading characters in the string. A subset established with this member function applies to only a ValueList object contained by an Attribute object. To retrieve all values in a ValueList object, set the string referenced by this member function to empty. For a complete discussion of SQL wildcards, see the Informix Guide to SQL: Syntax.

When you change the value returned by this member function, you should call OnSubsetChanged().

3-334 SDK for Snap-Ins Programmer’s Manual ValueList::GetTabbedValues

ValueList::GetArrayValues

VARIANT GetArrayValues();

Return Value

An OLE data type containing an OLE SafeArray.

Remarks

Call this member function to translate the contents of a ValueList object into an OLE SafeArray. For information on how to access an OLE SafeArray, refer to the Microsoft Visual C++ product documentation.

ValueList::GetTabbedValues

BSTR GetTabbedValues();

Return Value

An OLE string containing tab-delimited data.

Remarks

Call this member function to translate the contents of a ValueList object into a tab-delimited string.

MetaCube Class Library 3-335 ValueList::OnMaxRowsChanged

ValueList::OnMaxRowsChanged

void OnMaxRowsChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_maxRows() has changed.

ValueList::OnSortChanged

void OnSortChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_sort() has changed.

ValueList::OnSubsetChanged

void OnSubsetChanged();

Remarks

Call this member function to issue a notiﬁcation to MetaCube that the value returned by Get_m_subset() has changed.

3-336 SDK for Snap-Ins Programmer’s Manual Index Index

Summaries member A function 3-319 Abstract base class 1-5, 1-8, 3-33 Application for all collection class objects 3-46 identifying 3-42, 3-43 for all MetaCube objects 3-41 Arguments Accuracy of query for an extension specifying 3-235, 3-237 changing argument types 2-8 AddDefault() 3-133 changing descriptions 2-6 Adding list of those needed 3-106 an object to a collection of validating 2-9 to 2-12 Extension objects 3-110 Arguments() function Filter objects 3-133, 3-134, 3-135 in .cpp file 2-6, 3-29 FilterElement objects 3-129 ArgumentTypes Folder objects 3-148 list of those needed for an MetaCube objects 3-225 extension 3-106 objects of the same class 3-49 ArgumentTypes() function Query objects 3-228 in .cpp file 2-8, 3-30 QueryCategory objects 3-279 Array QueryItem objects 3-313 of null values Summary objects 3-319 macro for making 1-13 AddItem() 3-49 types 1-15 AddNewFilter() 3-134 Assigning AddSaved() 3-135 value Add() to a CDimKey object 3-27 Extensions member to a filter parameter 3-258 function 3-110 Attribute FilterElements member names in MetaCube object function 3-129 retrieving 3-213 Folders member function 3-148 object 3-287 MetaCubes member Author of a query function 3-225 identifying 3-235 Queries member function 3-228 Automatic execution of a QueryCategories member query 3-236 function 3-279 QueryItems member function 3-313 Cell type constants 3-199 not available through C++ API, B Cells illustrated 1-7 Boolean data type 1-10 in a CQueryCube object to which an object belongs Buffer sizes 1-14 counting 3-71 identifying 3-45 deleting 3-69 macro 1-12, 1-13 retrieving applicable dimension Classes C keys 3-78 to which extension functions retrieving indexes 3-76 apply 3-104, 3-107 CDb class 3-3 to 3-17, 3-95 retrieving value 3-74 Clearing Commit() 3-5 setting value 3-93 parameters applied to a DeleteString() 3-5 in a MetaCube object query 3-234 EndSelect() 3-6 retrieving data types 3-199, sorts in a MetaCube 3-194 ExecuteStmt() 3-210 ClearParameters() 3-234 requiring no runtime retrieving error values 3-198 ClearSorts() 3-194 arguments 3-7 retrieving values 3-197, 3-208, Client type constants 3-161 requiring runtime 3-216 CloseDSSSystem() 3-156 arguments 3-8 cell_error, member of an SCell Closing GetColumns() 3-10 structure 3-74, 3-93 the DSS System 3-156 GetDataSources() 3-11 cell_format, member of an SCell CMetaObject class 1-8, 3-33 to 3-38 GetString() 3-12 structure 3-74, 3-93 GetDirty() 3-35 GetTables() 3-13 cell_item_index, member of an GetVerified() 3-36 GetUsers() 3-14 SCell structure 3-74, 3-93 GetVerifyResults() 3-37 list of members 3-4 cell_value, member of an SCell list of members 3-34 PutString() 3-15 structure 3-74, 3-93 Verify() 3-38 Rollback() 3-15 Changes to a database Code for sample extension 2-21 SelectStmt() 3-16 confirming 3-5 COlapException class 3-39 to 3-40 CDb object undoing 3-15 Get_m_code() 3-40 identifying 3-166 Changing Get_m_reason() 3-40 CDimKey name of list of members 3-39 class 3-18 to 3-27 filter 3-120 COlapObject class 1-8, 3-41 to 3-45 CDimKey() 3-20 Query object 3-257 GetApplication() 3-43 Hash() 3-21 QueryCategory object 3-296 GetParent() 3-44 list of members 3-19 QueryItem object 3-310 GetRefCount() 3-44 m_group 3-21 Child object 1-5 GetType() 3-45 m_selfsort 3-22 Children of a CParseNode Get_m_application() 3-42 m_sortval 3-22 object 3-62 Get_m_iparent() 3-42 m_string 3-23 CIExtension Get_m_metabase() 3-43 operator<() 3-25 class 3-28 to 3-32 list of members 3-41 operator==() 3-26 list of members 3-28 COleCollection class 1-8, operator>() 3-24 m_arguments 3-29 3-46 to 3-58 SetFrom() 3-27 m_argumenttypes 3-30 AddItem() 3-49 objects m_processitem 3-31 GetCount() 3-50 assigning values 3-27 m_type 3-31 GetElementIndex() 3-50 comparing 3-24, 3-25, 3-26 m_validate 3-32 GetItem() 3-51 constructing 3-20 object 3-288 GetNames() 3-51 grouping 3-21 Class Get_m_count() 3-49 sorting 3-22 hierarchy IGetItem() 3-52 string value of 3-23 for C++ API, illustrated 1-6 IMakeNth() 3-53 CDimKey() 3-20 IRemoveAll() 3-53

2 SDK for Snap-Ins Programmer’s Manual list of members 3-47 Comparing CParseNode MakeFirst() 3-54 value of CDimKey objects 3-24, class 3-59 to 3-63 MakeLast() 3-54 3-25, 3-26 list of members 3-61 MakeNth() 3-55 Configuration of Metabase m_children 3-62 RemoveAll() 3-56 parameters, retrieving 3-162 m_number_val 3-62 RemoveItem() 3-57 Confirming m_state 3-62 Remove() 3-55 changes to a database 3-5 m_string_val 3-63 Swap() 3-58 Connect() 3-156 m_type 3-63 Collection Constants objects 2-11, 3-59 described 1-5 cell type 3-199 children of 3-62 member objects in a client type 3-161 for QueryCategory counting 3-49, 3-50 data skipping 3-165 objects 3-291 rearranging 3-53, 3-54, 3-55, defined in header file 1-11 for QueryItem objects 3-304 3-58 filter element 3-125 forming a hierarchical tree, removing 3-53, 3-55, 3-56, 3-57 frequency 3-260, 3-268 illustrated 3-60 retrieving index for 3-50 job status 3-270 numeric value 3-62 retrieving names for 3-51 orientation 3-239, 3-247, 3-257, string value 3-63 retrieving pointers to 3-51, 3-52 3-290 type 3-63 of Extension objects 3-109 sort direction 3-204, 3-206, 3-208, CPlugIn of Filter objects 3-132 3-292, 3-333 class 3-64 to 3-65 of FilterElement objects 3-128 summarization 3-319, 3-327 list of members 3-64 of Folder objects 3-146 vendor 3-163 m_dll 3-65 of MetaCube objects 3-224 verification 3-36, 3-38 m_extensions 3-65 of Query objects 3-227 Constructing object of QueryBackJob objects 3-274 a CDimKey object 3-20 encapsulated in a Snap-In 3-107 of QueryCategory objects 3-277 Copying CQueryCube rearranging 3-280, 3-281, 3-283 a MetaCube object 3-194 class 3-66 to 3-94 of QueryItem objects 3-311 Copy() 3-194 DeleteCell() 3-69 rearranging 3-314, 3-315, 3-316 Cost of query DeleteColumn() 3-69 of Summary objects 3-317 determining 3-242 DeletePage() 3-70 rearranging 3-321, 3-322, 3-323 Counting DeleteRow() 3-70 Column breaks cells in a QueryCube 3-71 GetCellItemIndex() 3-76 sorting within 3-203 columns in a MetaCube GetCellKey() 3-78 Columns object 3-211 GetCell() 3-74 in a CQueryCube object dimensions in a QueryCube 3-71 GetColDimIndexes() 3-79 deleting 3-69 Filter objects 3-136 GetColDims() 3-80 inserting 3-90 objects in a collection 3-49, 3-50 GetColLabels() 3-81 orientation of values 3-79, 3-80, pages GetDimCounts() 3-82 3-81 in a MetaCube object 3-214 GetPageDimIndexes() 3-83 in a MetaCube object in a QueryCube 3-73 GetPageDims() 3-84 counting 3-211 QueryCategory objects GetPageLabels() 3-85 sorting 3-215, 3-220 returning values to a GetPageSize() 3-86 sorting within 3-204 QueryCube 3-82 GetRowDimIndexes() 3-87 specifying 3-200 rows GetRowDims() 3-88 suppressing duplicate values and columns on a QueryCube GetRowLabels() 3-89 within 3-207 page 3-86 Get_m_cellcount() 3-71 Commit() 3-5 in a MetaCube object 3-214 Get_m_dimcount() 3-71 retrieved by calling Fetch() 3-97 Get_m_dimonly() 3-72 Get_m_iparent() 3-72

Index 3 Get_m_numpages() 3-73 Date reports measure data 3-72 InsertColumn() 3-90 current, retrieving 3-175 results reside in memory 3-243 InsertPage() 3-91 of last metadata QueryCategory expression has InsertRow() 3-92 modification 3-168 been parsed 3-291 list of members 3-67 query QueryItem expression has been SetCell() 3-93 was last changed 3-248 parsed 3-304 object DBLogin() 3-157 user has privileges retrieving 3-240 DBLogout() 3-157 to change filter 3-118 CreateNew() 3-156 Define() 3-96 Development environment, Creating Defining identifying 3-161 the DSS System 3-156 format of data in CSelect Dimension keys 3-18 to 3-27 CSelect object 3-96 comparing 3-24, 3-25, 3-26 class 3-95 to 3-97 DeleteCell() 3-69 grouping 3-21 Define() 3-96 DeleteColumn() 3-69 retrieving Fetch() 3-97 DeleteFilter() 3-114 for a cell in a QueryCube 3-78 list of members 3-95 DeleteJob() 3-264 sorting 3-22 RowCount() 3-97 DeleteMetaModel() 3-158 string value of 3-23 objects DeletePage() 3-70 DimensionElement object 3-287 defining their data formats 3-96 DeleteQuery() 3-159, 3-234 Dimensions destroying 3-6 DeleteRow() 3-70 in a CQueryCube object retrieving data from 3-97 DeleteString() 3-5 counting 3-71 C++ programming interface 1-3 Deleting object DSS system from metadata 3-158 identifying in DSS System 3-175 filters 3-114 Directory where MetaCube is D from a QueryCube installed cells 3-69 identifying 3-170 Data columns 3-69 Disconnecting in a MetaCube object pages 3-70 from a database 3-157 retrieving 3-222, 3-223 rows 3-70 DispIsA() macro 1-13 skipping query DLL file constants 3-165 definition from database 3-234 handle 3-65, 3-104 specifying 3-165 from metadata 3-159 DLLMAIN() function 2-6 source QueryBackJob 3-264 DoSQL() 3-160 for query, specifying 3-238 strings stored in a database 3-5 Double data type 1-10 type constants 3-8, 3-10 Derived classes 1-8 DrillDataSources collection types Destroying for query standard 1-10 a CSelect object 3-6 retrieving 3-244 Database Determining if DSS System connection filter definition has closing 3-156 class embodying 3-3 changed 3-118 creating 3-156 comparing to query Metabase object has connected to date of last update 3-168 definition 3-248 database 3-164 deleting from metadata 3-158 disconnecting 3-157 metadata object definition has names, retrieving 3-177 logging in 3-156, 3-157, 3-169 changed 3-35 opening 3-187 optimization, setting 3-171 query saving changes 3-188 schemas 3-180 definition matches database saving under new name 3-188 vendor connection 3-248 constants 3-163 filters on time 3-253 identifying 3-163 is saved to database 3-241

4 SDK for Snap-Ins Programmer’s Manual m_enabled 3-105 FetchCellError() 3-198 E m_fileName 3-105 FetchCellType() 3-199 Enabling m_iarguments 3-106 FetchCell() 3-197 an extension 3-105 m_iargumenttypes 3-106 Fetch() 3-97 EndSelect() 3-6 m_ifunctions 3-106 Filter Error m_itypes 3-107 changing name of 3-120, 3-144 code m_plugin 3-107 class 3-112 to 3-120 defined 1-10 OnEnabledChanged() 3-107 DeleteFilter() 3-114 retrieving 3-40 OnFinalRelease() 3-108 GetFilterElements() 3-116 returned by server 3-265 RefreshList() 3-108 GetFolder() 3-116 description, retrieving 3-40 Description GetName() 3-117 handling 3-39 text box in SDK Extension GetOwner() 3-117 margins Wizard 2-5 GetSaved() 3-118 for a cell, retrieving 3-209 file name 3-105 GetUpdatable() 3-118 for a query 3-196 retrieving 3-103 Get_m_enabled() 3-114 for a query, specifying 3-237 functions Get_m_group() 3-115 message returned by server 3-265 listed 3-106 Get_m_iparent() 3-115 results retrieving list of 3-103 list of members 3-113 in tab-delimited form 3-195 retrieving list of affected OnEnabledChanged() 3-119 ErrorSpreadClip() 3-195 classes 3-104 OnGroupChanged() 3-119 ErrorVBArray() 3-196 Name SaveAs() 3-120 error.h file 1-10, 3-40 text box in SDK Extension Save() 3-119 ExecuteStmt() Wizard 2-5 SetName() 3-120 requiring object determining if no runtime arguments 3-7 adding to a collection 3-110 definition has changed 3-118 runtime arguments 3-8 removing from a user can change 3-118 Executing collection 3-111 element constants 3-125 a query automatically 3-236 process code objects an SQL statement creating 2-12 to 2-17 adding to a collection 3-133, non-SELECT 3-7, 3-8, 3-160 sample 2-3 3-134, 3-135 that performs a query 3-16 code for 2-21 counting 3-136 Extension Extensions deleting 3-114 argument types class 3-109 to 3-111 grouping 3-115 listed 3-106 Add() 3-110 removing from a retrieving list of 3-102 list of members 3-109 collection 3-138 arguments OnFinalRelease() 3-110 retrieving indexes for 3-137 changing description 2-6 Remove() 3-111 retrieving names of 3-117, changing types 2-8 in a Snap-In 3-28, 3-65 3-141, 3-143 listed 3-106 needed for a query 3-288, 3-300 parameters retrieving list of 3-101 object assigning values 3-258 validating 2-9 to 2-12 identifying 3-176 undefined 3-251 class 3-98 to 3-108 registered, retrieving list of 3-166 preventing application to a GetArguments() 3-101 extensions.h file 2-8 query 3-114 GetArgumentTypes() 3-102 retrieving owners of 3-117 GetFileName() 3-103 saving 3-119 GetFunctions() 3-103 F with a name 3-120 FilterElement GetTypes() 3-104 FactTables object class 3-121 to 3-127 list of members 3-99 identifying 3-176 m_dll 3-104 GetFilterOn() 3-124

Index 5 GetFilterType() 3-125 RenameFilter() 3-144 GetCell() 3-208 GetObject() 3-126 RenameQuery() 3-145 CQueryCube member Get_m_iparent() 3-123 SetName() 3-145 function 3-74 Get_m_operand() 3-123 containing a filter MetaCube member Get_m_operator() 3-124 retrieving 3-116 function 3-208 list of members 3-122 containing a query GetColDimIndexes() 3-79 SetFilterOn() 3-127 retrieving 3-246 GetColDims() 3-80 objects naming 3-145 GetColLabels() 3-81 adding to a collection 3-129 objects GetColumns() removing from a adding to a collection 3-148 CDb member function 3-10 collection 3-131 removing from a MetaCube member FilterElements collection 3-149 function 3-211 class 3-128 to 3-131 retrieving 3-142 GetCost() 3-242 Add() 3-129 retrieving path to 3-142 GetCountGroup() 3-136 Get_m_iparent() 3-131 Folders class 3-146 to 3-149 GetCount() 3-50 list of members 3-128 Add() 3-148 GetCurrentAttribute() 3-212 OnOperandChanged() 3-126 Get_m_iparent() 3-148 GetCurrentData() 3-243 OnOperatorChanged() 3-126 list of members 3-147 GetCurrentTime() 3-175 Remove() 3-131 Remove() 3-149 GetDataSources() retrieving Format of a MetaCube CDb member function 3-11 for a filter 3-116 saving 3-202 GetDimCounts() 3-82 Filtering Formatting commands GetDimensions() 3-175 object type used for 3-125 for columns or rows GetDirty() 3-35 object used for 3-126 in a MetaCube object 3-213 GetDrillDataSources() 3-244 on time for numeric data 3-301, 3-306 GetElementIndex() 3-50 in a query 3-253 changing 3-309 GetErrorCode() 3-265 operator used for 3-124 Frequency GetErrorText() 3-265 values used for 3-123, 3-124 constants 3-260, 3-268 GetExecutionTime() 3-245 setting 3-127 of execution GetExtensions() 3-176 Filters for QueryBackJob 3-268 GetFactTables() 3-176 class 3-132 to 3-138 Functions included in extension GetFileName() 3-103 AddDefault() 3-133 list of 3-106 GetFilterElements() 3-116 AddNewFilter() 3-134 FunctionType of CParseNode GetFilterNames() 3-141 AddSave() 3-135 object 3-63 GetFilterOn() 3-124 GetCountGroup() 3-136 GetFilters() 3-245 GetItemGroup() 3-137 GetFilterType() 3-125 Get_m_iparent() 3-136 G GetFolders() 3-142 list of members 3-132 GetFolder() genclr() macro 1-13 Remove() 3-138 Filter member function 3-116 Get and Set collection Query member function 3-246 pairs of functions 1-16 applied to a query 3-245 GetFormatStrings() 3-213 GetApplication() 3-43 Folder GetFormatString() 3-306 GetArguments() 3-101 class 3-139 to 3-145 GetFullPathName() GetArgumentTypes() 3-102 GetFilterNames() 3-141 Folder member function 3-142 GetArrayValues() 3-335 GetFolders() 3-142 GetFunctions() 3-103 GetCellError() 3-209 GetFullPathName() 3-142 GetItemGroup() 3-137 GetCellItemIndex() 3-76 GetName() 3-143 GetItemOrientation() 3-247 GetCellKey() 3-78 GetQueryNames() 3-143 GetCellType() 3-210 list of members 3-140

6 SDK for Snap-Ins Programmer’s Manual GetItem() GetRefCount() 3-44 Get_m_confidence() 3-237 COleCollection member GetRootFolder() 3-179 related verification function 3-51 GetRowDimIndexes() 3-87 function 3-254 QueryItem member GetRowDims() 3-88 Get_m_configuration() 3-162 function 3-307 GetRowLabels() 3-89 related verification GetJobID() 3-266 GetRows() 3-214 function 3-182 GetLastUpdate() 3-248 GetSaved() 3-118 Get_m_connectDatabase() 3-163 GetLive() 3-248 GetSchemas() 3-180 related verification GetMaximumExceeded() 3-249 GetSize() 3-269 function 3-182 GetMetaCubes() 3-249 GetSortColumn() 3-215 Get_m_connected() 3-164 GetMetaModelNames() 3-177 GetSQL() 3-253 Get_m_connectString() 3-164 GetNames() 3-51 GetStartTime() 3-269 related verification GetName() 3-307 GetStatus() 3-270 function 3-183 Filter member function 3-117 GetStopTime() 3-271 Get_m_count() 3-49 Folder member function 3-143 GetString() 3-12 Get_m_dataSkip() 3-165 Query member function 3-250 GetSubmitTime() 3-271 related verification QueryBackJob member GetSummaries() 3-216 function 3-183 function 3-266 GetSystemMessages() 3-180 Get_m_dataSource() 3-238 QueryCategory member GetTabbedValues() 3-335 related verification function 3-293 GetTables() 3-13 function 3-254 GetObject() 3-126 GetTargetStart() 3-272 Get_m_db() 3-166 QueryCategory member GetTimeFiltered() 3-253 Get_m_dimcount() 3-71 function 3-294 GetTypes() 3-104 Get_m_dimonly() 3-72 QueryItem member GetType() 3-45 Get_m_enabled() 3-114 function 3-308 GetUniqueID() 3-181 related verification GetOwner() 3-117 GetUpdatable() 3-118 function 3-119 GetPageDimIndexes() 3-83 GetUsers() 3-14 Get_m_explain() 3-167 GetPageDims() 3-84 GetValue() 3-216 related verification GetPageLabels() GetVerified() 3-36 function 3-183 CQueryCube function 3-85 GetVerifyResults() 3-37 Get_m_extensions() MetaCube function 3-213 Get_m_ functions Metabase member function 3-166 GetPageSize() 3-86 explained 1-16 QueryItem member GetPages() 3-214 Get_m_accuracy() 3-235 function 3-300 GetParameterObject() 3-250 related verification Get_m_extension() 3-288 GetParameterOperator() 3-251 function 3-254 Get_m_formatString() 3-301 GetParameters() 3-251 Get_m_application() 3-42 Get_m_group() 3-115 GetParent() Get_m_author() 3-235 related verification COlapObject member Get_m_autoRefresh() 3-236 function 3-119 function 3-44 Get_m_category() 3-287, 3-291 Get_m_iparent() Metabase member function 3-177 Get_m_cellcount() 3-71 COlapObject member GetPriority() 3-267 Get_m_clientType() 3-161 function 3-42 GetPublicUser() 3-178 related verification CQueryCube member GetQueries() 3-178 function 3-182 function 3-72 GetQueryBackJobs() 3-179 Get_m_code() 3-40 Filter member function 3-115 GetQueryCategories() 3-252 Get_m_column() 3-200 FilterElement member GetQueryCategory() 3-328 related verification function 3-123 GetQueryItems() 3-252 function 3-217 FilterElements member GetQueryNames() 3-143 function 3-131 GetRecurType() 3-268 Filters member function 3-136

Index 7 Folders member function 3-148 Get_m_numpages() 3-73 related verification MetaCube member Get_m_object() function 3-218 function 3-200 QueryCategory member Get_m_sortColumn- MetaCubes member function 3-289 Direction() 3-204 function 3-225 QueryItem member related verification Queries member function 3-228 function 3-303 function 3-218 Query member function 3-238 Get_m_operand() 3-123 Get_m_sortDirection() 3-292 QueryBackJob member related verification related verification function 3-264 function 3-126 function 3-295 QueryBackJobs member Get_m_operator() 3-124 Get_m_sortRowBreaks() 3-205 function 3-275 related verification related verification QueryCategories member function 3-126 function 3-219 function 3-280 Get_m_optimization() 3-171 Get_m_sortRowDirection() 3-206 QueryCategory member related verification related verification function 3-288 function 3-185 function 3-219 QueryItem member Get_m_orientation() 3-290 Get_m_sort() 3-333 function 3-302 related verification related verification QueryItems member function 3-295 function 3-336 function 3-313 Get_m_page() 3-201 Get_m_subset() 3-334 Summaries member Get_m_parsed() related verification function 3-321 QueryCategory member function 3-336 Summary member function 3-326 function 3-291 Get_m_summaryType() 3-327 ValueList member function 3-332 QueryItem member related verification Get_m_itemOrientation() 3-239 function 3-304 function 3-329 Get_m_item() 3-302, 3-304 Get_m_parse() Get_m_suppressDialogs() 3-174 Get_m_lastUpdate() 3-168 QueryCategory member Get_m_suppressDuplicates() 3-207 Get_m_localMetamodelFile() 3-168 function 3-291 related verification related verification QueryItem member function 3-219 function 3-184 function 3-304 Get_m_type() Get_m_login() 3-169 Get_m_password() 3-172 QueryCategory member related verification related verification function 3-293 function 3-184 function 3-185 QueryItem member Get_m_maxRows() 3-332 Get_m_pDQPriority() 3-173 function 3-305 related verification related verification Grouping function 3-336 function 3-185 CDimKey objects 3-21 Get_m_maxTotalFetches() 3-169 Get_m_qcube() 3-240 within a query Get_m_metabase() 3-43 Get_m_queryCategory() 3-326 defining 3-287 Get_m_metacube_path() 3-170 Get_m_reason() 3-40 Get_m_name() 3-303 Get_m_referenceCount() 3-241 Metabase member function 3-170 Get_m_row() 3-202 H related verification related verification Hash() 3-21 function 3-185 function 3-218 Header files 1-10 MetaCube member Get_m_saved() 3-241 error.h 1-10 function 3-201 Get_m_schema() 3-174 metacons.h 1-11 related verification related verification sdk.h 1-12 function 3-217 function 3-184 Hierarchy charts Query member function 3-240 Get_m_scratch() 3-202 explained 1-8 QueryCategory member Get_m_sortColumnBreaks() 3-203 function 3-289

8 SDK for Snap-Ins Programmer’s Manual Hypercube SystemMessages object making an array of nulls 1-13 of data 3-66 for Metabase object 3-180 making null pointer 1-14 IDispatch making null value 1-14 object 3-181 MakeFirst() I pointer COleCollection member mapping 3-181 function 3-54 Identifying IGetItem() 3-52 QueryCategories member author of a query 3-235 IMakeNth() 3-53 function 3-280 CDb object 3-166 Inheritance 1-8 QueryItems member class to which object belongs 3-45 Initialization file 3-98 function 3-314 database vendor 3-163 InsertColumn() 3-90 Summaries member development environment 3-161 Inserting function 3-321 DSS Systems a column into a QueryCube 3-90 MakeLast() Dimensions object 3-175 a page into a QueryCube 3-91 COleCollection member FactTables object 3-176 a row into a QueryCube 3-92 function 3-54 folder holding a query 3-246 InsertPage() 3-91 QueryCategories member Metabase collection of InsertRow() 3-92 function 3-281 Extensions object 3-176 Instantiating QueryItems member Query objects 3-178 a query in metadata 3-186 function 3-314 QueryBackJob objects 3-179 IRemoveAll() 3-53 Summaries member Schema objects 3-180 IsA() macro 1-12 function 3-322 ODBC data sources 3-164 ItemJobID() 3-276 MakeNth() parent of a COleCollection member COlapObject object 3-42, 3-44 function 3-55 CQueryCube object 3-72 J QueryCategories member Filter object 3-115 function 3-281 FilterElement object 3-123 Job ID QueryItems member FilterElements object 3-131 assigned by server function 3-315 Filters object 3-136 while processing Summaries member Folders object 3-148 QueryBackJob 3-266 function 3-322 MetaCube object 3-200 Job status MAKENULLS() macro 1-13 MetaCubes object 3-225 constants 3-270 Maximum number of rows Queries object 3-228 of QueryBackJob 3-270 returned by query 3-249 Query object 3-238 returned from ValueList QueryBackJob object 3-264 object 3-332 QueryBackJobs object 3-275 L MCXSDK_ VERSION 3-64 QueryCategories object 3-280 Logging Measure data QueryCategory object 3-288 into database 3-156, 3-157, 3-169, reported by a query 3-72 QueryItem object 3-302 3-172 Measure object QueryItems object 3-313 out from database 3-157 used for query 3-302, 3-307 Summaries object 3-321 Long data type 1-10 changing 3-310 Summary object 3-326 Memory ValueList object 3-332 macro for clearing 1-13 public user 3-178 M Metabase QueryCategory object class 3-150 to 3-188 included in filter Macro CloseDSSSystem() 3-156 definition 3-250 clearing memory 1-13 Connect() 3-156 RootFolder object 3-179 determining class CreateNew() 3-156 membership 1-12, 1-13 DBLogin() 3-157

Index 9 DBLogout() 3-157 OnConnectString- Get_m_scratch() 3-202 DeleteMetaModel() 3-158 Changed() 3-183 Get_m_sortColumn- DeleteQuery() 3-159 OnDataSkipChanged() 3-183 Breaks() 3-203 DoSQL() 3-160 OnExplainChanged() 3-183 Get_m_sortColumnDirection() GetCurrentTime() 3-175 OnLocalMetamodelFile- 3-204 GetDimensions() 3-175 Changed() 3-184 Get_m_sortRowBreaks() 3-205 GetExtensions() 3-176 OnLoginChanged() 3-184 Get_m_sortRow- GetFactTables() 3-176 OnMetaSchemaChanged() 3-18 Direction() 3-206 GetlMetaModelNames() 3-177 4 Get_m_suppress- GetParent() 3-177 OnNameChanged() 3-185 Duplicates() 3-207 GetPublicUser() 3-178 OnOptimization- hierarchy, illustrated 1-6, 1-7 GetQueries() 3-178 Changed() 3-185 library 1-8 GetQueryBackJobs() 3-179 OnPasswordChanged() 3-185 list of members 3-190 GetRootFolder() 3-179 OnPDQPriority- OnColumnBreaks- GetSchemas() 3-180 Changed() 3-185 Changed() 3-218 GetSystemMessages() 3-180 OpenDSSSystem() 3-187 OnColumnChanged() 3-217 GetUniqueID() 3-181 OpenQueryStorage() 3-187 OnColumnDirectionChanged() Get_m_clientType() 3-161 OpenQuery() 3-186 3-218 Get_m_configuration() 3-162 SaveAs() 3-188 OnNameChanged() 3-217 Get_m_connect- Save() 3-188 OnRowChanged() 3-218 Database() 3-163 object 3-65 OnSortRowBreaks- Get_m_connected() 3-164 retrieving 3-43 Changed() 3-219 Get_m_connectString() 3-164 metacons.h file 1-11 OnSortRowDirectionChanged() Get_m_dataSkip() 3-165 MetaCube 3-219 Get_m_db() 3-166 class 3-189 to 3-223 OnSuppressDuplicates- Get_m_explain() 3-167 ClearSorts() 3-194 Changed() 3-219 Get_m_extensions() 3-166 Copy() 3-194 SetSortColumn() 3-220 Get_m_lastUpdate() 3-168 ErrorSpreadClip() 3-195 SetSortRow() 3-221 Get_m_localMetamodel- ErrorVBArray() 3-196 ToSpreadClip() 3-222 File() 3-168 FetchCellError() 3-198 ToVBArray() 3-223 Get_m_login() 3-169 FetchCellType() 3-199 engine, identifying 3-42, 3-43 Get_m_maxTotal- FetchCell() 3-197 objects Fetches() 3-169, 3-249 GetCellError() 3-209 adding to a collection 3-225 Get_m_metacube_path() 3-170 GetCellType() 3-210 clearing sorts from 3-194 Get_m_name() 3-170 GetCell() 3-208 copying 3-194 Get_m_optimization() 3-171 GetColumns() 3-211 removing from a Get_m_password() 3-172 GetCurrentAttribute() 3-212 collection 3-226 Get_m_pDQPriority() 3-173 GetFormatStrings() 3-213 MetaCubes Get_m_schema() 3-174 GetPageLabels() 3-213 class 3-224 to 3-226 Get_m_suppress- GetPages() 3-214 Add() 3-225 Dialogs() 3-174 GetRows() 3-214 Get_m_iparent() 3-225 list of members 3-151 GetSortColumn() 3-215 list of members 3-224 ObjFromIDispatch() 3-181 GetSummaries() 3-216 Remove() 3-226 OnClientTypeChanged() 3-182 GetValue() 3-216 collection OnConfiguration- Get_m_column() 3-200 associated with query 3-249 Changed() 3-182 Get_m_iparent() 3-200 Metacube.ini file 3-98, 3-105, 3-162 OnConnectDatabaseChanged() Get_m_name() 3-201 MetamodelFile parameter 3-168 3-182 Get_m_page() 3-201 MetamodelSchema Get_m_row() 3-202 parameter 3-174

10 SDK for Snap-Ins Programmer’s Manual Metadata NameType of CParseNode OnAccuracyChanged() 3-254 classes 1-4 object 3-63 OnClientTypeChanged() 3-182 illustrated 1-7 Naming OnColumnBreaksChanged() 3-218 file, storing local copy of 3-168 a filter 3-120, 3-144 OnColumnChanged() 3-217 objects a folder 3-145 OnColumnDirection- determining if definitions have a query 3-145 Changed() 3-218 changed 3-35 restrictions OnConfidenceChanged() 3-254 verifying 3-38 for objects 1-9 OnConfigurationChanged() 3-182 retrieving schema from 3-174 Null OnConnectDatabase- m_arguments 3-29 pointer Changed() 3-182 m_argumenttypes 3-30 macro for making 1-14 OnConnectStringChanged() 3-183 m_children 3-62 value OnDataSkipChanged() 3-183 m_dll array, macro for making 1-13 OnDataSourceChanged() 3-254 CPlugIn class data member 3-65 macro for making 1-14 OnEnabledChanged() 3-107, 3-119 Extension class data NULLP() macro 1-14 OnExplainChanged() 3-183 member 3-104 NULLV() macro 1-14 OnFinalRelease() 3-108, 3-110 m_enabled 3-105 Number of Arguments OnGroupChanged() 3-119 related notification text box in SDK Extension OnLocalMetamodelFile- function 3-107 Wizard 2-5 Changed() 3-184 m_extensions 3-65 NumberType of CParseNode OnLoginChanged() 3-184 m_fileName 3-105 object 3-63 OnMaxRowsChanged() 3-336 m_group 3-21 Numeric OnMetaSchemaChanged() 3-184 m_iarguments 3-106 data OnNameChanged() 3-185, 3-217 m_iargumenttypes 3-106 formatting 3-301, 3-306, 3-309 OnOperandChanged() 3-126 m_ifunctions 3-106 value OnOperatorChanged() 3-126 m_itypes 3-107 of a CParseNode object 3-62 OnOptimizationChanged() 3-185 m_number_val 3-62 OnOrientationChanged() 3-295 m_plugin 3-107 OnPasswordChanged() 3-185 m_processitem 3-31 O OnPDQPriorityChanged() 3-185 m_selfsort 3-22 OnRowChanged() 3-218 Object m_sortval 3-22 OnSortChanged() 3-336 adding to a collection 3-49 m_state 3-62 OnSortDirectionChanged() 3-295 hierarchies 1-4, 1-5 m_string 3-23 OnSortRowBreaksChanged() 3-219 naming restrictions 1-9 m_string_val 3-63 OnSortRowDirection- used to create m_type 3-31, 3-63 Changed() 3-219 QueryCategory m_validate 3-32 OnSubsetChanged() 3-336 expression 3-289, 3-294 OnSummaryTypeChanged() 3-329 QueryItem expression 3-303, OnSuppressDuplicatesChanged() 3-308 N 3-219 ObjFromIDispatch() 3-181 OpenDSSSystem() 3-187 Name ODBC data sources Opening of file containing compiled identifying 3-164 a DSS System 3-187 extension code 3-105 retrieving 3-11 OpenQueryStorage() 3-187 retrieving for a OLE OpenQuery() 3-186 DSS System 3-170 automation 1-3, 1-4 Operator MetaCube object 3-201 programming interface 1-3 for undefined parameter Query object 3-240 reference count retrieving 3-251 QueryBackJob object 3-266 retrieving 3-44 operator<() 3-25 SafeArray 3-335 operator==() 3-26

Index 11 operator>() 3-24 Summary object 3-326 GetMetaCubes() 3-249 Orientation ValueList object 3-332 GetName() 3-250 constants 3-239, 3-247, 3-257, Password GetParameterObject() 3-250 3-290 retrieving 3-172 GetParameterOperator() 3-251 of measures returned by PDQ Priority GetParameters() 3-251 query 3-239, 3-247, 3-257 setting 3-173 GetQueryCategories() 3-252 of values in a QueryCube 3-82 plugin.h 3-64 GetQueryItems() 3-252 of values returned by Preventing GetSQL() 3-253 QueryCategory 3-290 filter from being applied to a GetTimeFiltered() 3-253 Overloaded operator function query 3-114 Get_m_accuracy() 3-235 for comparing CDimkey Priority assigned to QueryBackJob Get_m_author() 3-235 objects 3-24, 3-25, 3-26 by server 3-267 Get_m_autoRefresh() 3-236 Process performed by extension Get_m_confidence() 3-237 creating 2-12 to 2-17 Get_m_dataSource() 3-238 P Process() function Get_m_iparent() 3-238 in .cpp file 2-12 to 2-17, 3-31 Get_m_itemOrientation() 3-239 Pages understanding 2-12 Get_m_name() 3-240 in a MetaCube object Public user Get_m_qcube() 3-240 counting 3-214 identifying 3-178 Get_m_referenceCount() 3-241 specifying 3-201 PutString() 3-15 Get_m_saved() 3-241 in a QueryCube OnAccuracyChanged() 3-254 counting 3-73 OnConfidenceChanged() 3-254 deleting 3-70 Q OnDataSourceChanged() 3-254 determining size 3-86 Retrieve() 3-255 inserting 3-91 Queries SaveAs() 3-256 orientation of values 3-83, 3-84, class 3-227 to 3-229 SaveStorage() 3-256 3-85 Add() 3-228 Save() 3-255 Parameters applied to a query Get_m_iparent() 3-228 SetItemOrientation() 3-257 clearing 3-234 list of members 3-227 SetName() 3-257 Parent object 1-5 Remove() 3-229 SetParameters() 3-258 identifying for executing SQL statements that SetSQL() 3-259 COlapObject 3-42, 3-44 perform 3-16 Submit() 3-260 CQueryCube object 3-72 object cost Filter object 3-115 identifying 3-178 determining 3-242 FilterElement object 3-123 Query definition FilterElements object 3-131 changing name of 3-145 deleting from database 3-234 Filters object 3-136 class 3-230 to 3-260 saving 3-255 Folders object 3-148 ClearParameters() 3-234 saving to a storage object 3-256 MetaCube object 3-200 DeleteQuery() 3-234 saving under a name 3-256 MetaCubes object 3-225 GetCost() 3-242 deleting from metadata 3-159 Queries object 3-228 GetCurrentData() 3-243 determining if saved to Query object 3-238 GetDrillDataSources() 3-244 database 3-241 QueryBackJob object 3-264 GetExecutionTime() 3-245 error margins 3-196 QueryBackJobs object 3-275 GetFilters() 3-245 grouping, defining 3-287 QueryCategories object 3-280 GetFolder() 3-246 instantiating in metadata 3-186 QueryCategory object 3-288 GetItemOrientation() 3-247 object QueryItem object 3-302 GetLastUpdate() 3-248 adding to a collection 3-228 QueryItems object 3-313 GetLive() 3-248 name, changing 3-257 Summaries object 3-321 GetMaximumExceeded() 3-249 name, retrieving 3-250

12 SDK for Snap-Ins Programmer’s Manual removing from a MakeNth() 3-281 sorting values 3-292 collection 3-229 Remove() 3-282 specifying order in retrieving name 3-143 Swap() 3-283 collection 3-281 saved in storage object 3-187 collection swapping position in results for a query 3-252 collection 3-283 residing in memory 3-243 returning values to a QueryCube QueryCube. See CQueryCube. retrieving 3-273 counting 3-82 QueryItem submitting for processing 3-260 in column orientation 3-79, class 3-297 to 3-310 summarizations 3-327 3-80, 3-81 GetFormatString() 3-306 time needed to execute 3-245 in page orientation 3-83, 3-84, GetItem() 3-307 QueryBackJob 3-85 GetName() 3-307 class 3-261 to 3-273 in row orientation 3-87, 3-88, GetObject() 3-308 DeleteJob() 3-264 3-89 Get_m_extensions() 3-300 GetErrorCode() 3-265 QueryCategory Get_m_formatString() 3-301 GetErrorText() 3-265 class 3-284 to 3-296 Get_m_iparent() 3-302 GetJobID() 3-266 GetName() 3-293 Get_m_item() 3-302 GetName() 3-266 GetObject() 3-294 Get_m_name() 3-303 GetPriority() 3-267 Get_m_category() 3-287 Get_m_object() 3-303 GetRecurType() 3-268 Get_m_extension() 3-288 Get_m_parsed() 3-304 GetSize() 3-269 Get_m_iparent() 3-288 Get_m_parse() 3-304 GetStartTime() 3-269 Get_m_name() 3-289 Get_m_type() 3-305 GetStatus() 3-270 Get_m_object() 3-289 list of members 3-298 GetStopTime() 3-271 Get_m_orientation() 3-290 SetFormatString() 3-309 GetSubmitTime() 3-271 Get_m_parsed() 3-291 SetItem() 3-310 GetTargetStart() 3-272 Get_m_parse() 3-291 SetName() 3-310 Get_m_iparent() 3-264 Get_m_sortDirection() 3-292 expression 3-302, 3-304, 3-307 list of members 3-262 Get_m_type() 3-293 changing 3-310 RefreshStatus() 3-272 list of members 3-285 classifying 3-305 Retrieve() 3-273 OnOrientationChanged() 3-295 name 3-303, 3-307 deleting 3-264 OnSortDirectionChanged() 3-2 changing 3-310 object 3-260 95 object 2-11 in a collection, retrieving 3-276 SetName() 3-296 adding to a collection 3-313 values, obtaining the expression 3-291 moving in a collection 3-314 current 3-272, 3-275 classifying 3-293 removing from a QueryBackJobs defining grouping in collection 3-315 class 3-274 to 3-276 query 3-287 specifying order in Get_m_iparent() 3-275 object 2-11 collection 3-315 ItemJobID() 3-276 adding to a collection 3-279 swapping position in list of members 3-274 defining grouping in a collection 3-316 RefreshStatus() 3-275 query 3-326, 3-328, 3-329 QueryItems object included in filter class 3-311 to 3-316 identifying 3-179 definition 3-250 Add() 3-313 QueryCategories label 3-293, 3-296 Get_m_iparent() 3-313 class 3-277 to 3-283 moving in a collection 3-280, list of members 3-312 Add() 3-279 3-281 MakeFirst() 3-314 Get_m_iparent() 3-280 name 3-289 MakeLast() 3-314 list of members 3-278 removing from a MakeNth() 3-315 MakeFirst() 3-280 collection 3-282 Remove() 3-315 MakeLast() 3-281 retrieving the current 3-212 Swap() 3-316

Index 13 collection Replacing column to be sorted 3-215 for a query 3-252 an SQL statement for a data 3-222, 3-223 query 3-259 formatting commands 3-213 Resource file row to be sorted 3-215 R for project 2-6 Summaries collection 3-216 resource.h file 1-12 from a QueryCube Rearranging Retrieve() dimension keys for cell 3-78 objects in a collection 3-53, 3-54, Query member function 3-255 index for cell 3-76 3-55, 3-58 QueryBackJob member value of a cell 3-74 Recording function 3-273 group query information 3-167 Retrieving associated with filter 3-115 RefreshList() 3-108 CIExtension object 3-288 index RefreshStatus() 3-261 classes for Filter objects 3-137 QueryBackJob member to which extension functions for object in a collection 3-50 function 3-272 apply 3-104 information about a table QueryBackJobs member configuration of Metabase owned by a user or schema 3-10 function 3-275 parameters 3-162 list of RemoveAll() 3-56 CParseNode object classes to which extension RemoveItem() 3-57 for QueryCategory object 3-291 functions apply 3-104 Remove() 3-55 CParseNode objects functions in an extension 3-103 Extensions member for QueryItem objects 3-304 registered extensions 3-166 function 3-111 CQueryCube object 3-240 tables owned by a user or FilterElements member data in CSelect object 3-97 schema 3-13 function 3-131 date and time 3-175 users or schemas 3-14 Filters member function 3-138 query was last changed 3-248 Metabase object 3-43 Folders member function 3-149 descriptions MetaCubes collection MetaCubes member of argument types in an for query 3-249 function 3-226 extension function 3-102 name of Queries member function 3-229 of arguments in an extension DSS System 3-170 QueryCategories member function 3-101 file containing extension function 3-282 DrillDataSources collection code 3-103 QueryItems member for query 3-244 MetaCube object 3-201 function 3-315 DSS System names 3-177 Query object 3-240 Summaries member error names of function 3-323 codes 3-40 Filter objects 3-117, 3-141 Removing descriptions 3-40 Folder objects 3-143 from a collection margins for a cell 3-209 objects in a collection 3-51 Extension objects 3-111 FilterElements object queries associated with a Filter objects 3-138 associated with filter 3-116 folder 3-143 FilterElement objects 3-131 Filters collection object Folder objects 3-149 applied to a query 3-245 type used for filtering 3-125 MetaCube objects 3-226 Folder object 3-142 used for filtering 3-126 objects 3-53, 3-55, 3-56, 3-57 containing a filter 3-116 used to create QueryCategory Query objects 3-229 from a MetaCube object expression 3-289, 3-294 QueryCategory objects 3-282 attribute names 3-213 used to create QueryItem QueryItem objects 3-315 cell data types 3-210 expression 3-303, 3-308 Summary objects 3-323 cell error values 3-198 ODBC data sources 3-11 RenameFilter() 3-144 cell value 3-216 OLE reference count for an RenameQuery() 3-145 cell values 3-208 object 3-44

14 SDK for Snap-Ins Programmer’s Manual operator QueryItems Save() 3-119, 3-188, 3-255 for undefined parameter 3-251 collection for a query 3-252 Saving used for filtering 3-124 rows, maximum number 3-169 a filter 3-119, 3-120 orientation SQL statement for a query 3-253 changes to a DSS System 3-188 of QueryCategory values 3-290 string stored in a database 3-12 DSS System owner subset of ValueList under a new name 3-188 of Filter object 3-117 contents 3-334 query definition 3-255 path to undefined filter parameters to a storage object 3-256 Folder objects 3-142 for query 3-251 under a name 3-256 pointers values used for filtering 3-123, SCell structure 1-15, 3-74, 3-93 to objects in a collection 3-51, 3-124 Scheduling daemon 3-261 3-52 verification results 3-36, 3-37 Schemas Query object name 3-250 Rollback() 3-15 for metadata tables, QueryBackJob object RootFolder object 3-146 retrieving 3-174 current values 3-272, 3-275 identifying 3-179 object error code 3-265 Row identifying 3-180 error message 3-265 breaks retrieving a list of 3-14 frequency 3-268 sorting within 3-205 Scratch 3-202 from a collection 3-276 in a MetaCube object SDK Extension Wizard job ID 3-266 sorting 3-215, 3-221 accessing 2-4 name 3-266 specifying 3-202 editing the template code 2-6 priority 3-267 orientation types of user 3, 4 results 3-273 of values in a QueryCube 3-87, using 2-3 to 2-20 rows returned to client 3-269 3-88, 3-89 Step 1 2-4 status 3-270 RowCount() 3-97 Step 2 2-5 time processing begins 3-269 Rows sdk.h file 1-12, 3-74, 3-93 time processing in a MetaCube object buffer sizes 1-14 completes 3-271 counting 3-214 macros 1-12 time requested for sorting within 3-206, 3-208 DispIsA() 1-13 processing 3-272 suppressing duplicate values genclr() 1-13 time submitted 3-271 within 3-207 IsA() 1-12 QueryCategories in a QueryCube MAKENULLS() 1-13 collection for a query 3-252 deleting 3-70 NULLP() 1-14 QueryCategory object inserting 3-92 NULLV() 1-14 associated with current query maximum number to be templated array types 1-15 value 3-212 retrieved 3-169 SelectStmt() 3-16, 3-95 defining grouping in a from ValueList object 3-332 SET EXPLAIN 3-167 query 3-326, 3-328, 3-329 retrieved with Fetch() SET OPTIMIZATION 3-171 label 3-293 counting 3-97 SET PDQPRIORITY 3-173 name 3-289 returned by QueryBackJob 3-269 SetCell() 3-93 returning values in column SetFilterOn() 3-127 orientation 3-79, 3-80, 3-81 SetFormatString() 3-309 returning values in page S SetFrom() 3-27 orientation 3-83, 3-84, 3-85 SetItemOrientation() 3-257 Sample extension 2-3 returning values in row SetItem() 3-310 code for 2-21 orientation 3-87, 3-88, 3-89 SetName() 3-310 Sample tables 3-235 QueryItem object Filter member function 3-120 SaveAs() 3-120, 3-188, 3-256 name 3-303, 3-307 Folder member function 3-145 SaveStorage() 3-256 Query member function 3-257

Index 15 QueryCategory member getting 3-12 QueryCategories member function 3-296 storing 3-15 function 3-283 SetParameters() 3-258 table 2-6, 3-29 QueryItems member SetQueryCategory() 3-329 value function 3-316 SetSortColumn() 3-220 of a CDimKey object 3-23 Summaries member SetSortRow() 3-221 of a CParseNode object 3-63 function 3-323 SetSQL() 3-259 Submitting SystemMessages object Setting a query for processing 3-260 identifying 3-180 column in a MetaCube object Submit() 3-260 to be sorted 3-220 Summaries database optimization 3-171 class 3-317 to 3-323 T PDQ Priority 3-173 Add() 3-319 Tab-delimited row in a MetaCube object Get_m_iparent() 3-321 data 3-222 to be sorted 3-221 list of members 3-318 in a ValueList object 3-335 value of a cell in a MakeFirst() 3-321 error results 3-195 QueryCube 3-93 MakeLast() 3-322 Tables values used for filtering 3-127 MakeNth() 3-322 owned by a user or schema Snap-In 3-64 Remove() 3-323 retrieving a list of 3-13 editing code in 2-6 Swap() 3-323 retrieving information extensions 3-28, 3-65 collection about 3-10 generating a template 2-4 in a MetaCube object, Templated array types 1-15 Sort direction constants 3-204, sorting 3-216 Time 3-206, 3-208, 3-292, 3-333 Summarization constants 3-319, current, retrieving 3-175 Sorting 3-327 needed to execute query 3-245 CDimKey objects 3-22 Summarizing query values returned by within query groupings 3-327 was last changed 3-248 QueryCategory object 3-292 Summary QueryBackJob ValueList object 3-333 class 3-324 to 3-329 is submitted 3-271 within MetaCube GetQueryCategory() 3-328 processing begins 3-269 columns 3-203, 3-204 Get_m_iparent() 3-326 processing finishes 3-271 rows 3-205, 3-206, 3-208 Get_m_queryCategory() 3-326 was requested 3-272 SQL statement Get_m_summaryType() 3-327 ToSpreadClip() 3-222 executing list of members 3-325 ToVBArray() 3-223 non-SELECT 3-7, 3-8, 3-160 OnSummaryTypeChanged() 3- Transmitting to perform a query 3-16 329 SQL statement for a query SetQueryCategory() 3-329 for a query 3-255 replacing 3-259 objects in a collection TupleType of CParseNode retrieving 3-253 adding 3-319 object 3-63 transmitting 3-255 removing 3-323 Type of CParseNode object 3-63 Status windows re-ordering 3-321, 3-322 suppressing 3-174 swapping position 3-323 Storage object containing a Query Suppressing U object 3-187 duplicate values in rows or Storing columns 3-207 Undoing a string in a database 3-15 MetaCube status windows 3-174 changes to a database 3-15 String Swap() Unique ID data type 1-10 COleCollection member obtaining for multi- in a database function 3-58 threading 3-181 deleting 3-5

16 SDK for Snap-Ins Programmer’s Manual Users of the SDK Extension Wizard 3, 4 Symbols retrieving a list of 3-14 .cpp file 3-28 Arguments() function 2-6 ArgumentTypes() function 2-8 V editing sample code 2-6 Validate() function generating a template 2-4 in .cpp file 2-9 to 2-12, 3-32 Process() function 2-12 to 2-17 understanding 2-11 Validate() function 2-9 to 2-12 ValueList .dll file 2-6 class 3-330 to 3-336 .mcx file 3-64, 3-65, 3-104, 3-107 GetArrayValues() 3-335 GetTabbedValues() 3-335 Get_m_iparent() 3-332 Get_m_maxRows() 3-332 Get_m_sort() 3-333 Get_m_subset() 3-334 list of members 3-331 OnMaxRowsChanged() 3-336 OnSortChanged() 3-336 OnSubsetChanged() 3-336 object data, sorting 3-333 described 1-9 subset of contents 3-334 translating into OLE SafeArray 3-335 translating into tab-delimited data 3-335 Variant array containing error margin values 3-196 Verification constants 3-36, 3-38 results retrieving 3-36, 3-37 Verifying metadata definitions 3-38 Verify() 3-38 Virtual function 3-55 Visual Basic 3-223

W Wildcard 3-334

Index 17 18 SDK for Snap-Ins Programmer’s Manual