metacube sdk for snap-ins programmer's manual · sdk for snap-ins programmer’s manual...

SDK for Snap-InsProgrammer’s Manual

TM
MetaCube ROLAP Option
for Informix Dynamic Server® TM

Version 4.0January 1998Part No. 000-4194

ii SDK for Snap-Ins Pro

Published by INFORMIX Press Informix Software, Inc.4100 Bohannon DriveMenlo Park, CA 94025-1032

Copyright 1981-1998 by Informix Software, Inc. or its subsidiaries, provided that portions may becopyrighted 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 theUnited 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) iffor civilian agency use, with Restricted Rights as defined in FAR 52.227-19; (2) if for Dept. of Defense use, withrights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribedin DFAR 227.7202. Any whole or partial reproduction of software or documentation marked with this legendmust reproduce the legend.

grammer’s Manual

Table of Contents

Table ofContents

IntroductionAbout This Manual . . . . . . . . . . . . . . . . . . 3

Organization of this Manual . . . . . . . . . . . . . 3Types of User . . . . . . . . . . . . . . . . . . 4

Documentation . . . . . . . . . . . . . . . . . . . 4Printed Documentation . . . . . . . . . . . . . . . 4Online Help . . . . . . . . . . . . . . . . . . . 6Readme Files . . . . . . . . . . . . . . . . . . 7Related Reading . . . . . . . . . . . . . . . . . 7

Compliance with Industry Standards . . . . . . . . . . . 8Informix Welcomes Your Comments . . . . . . . . . . . . 8

Chapter 1 Basic ConceptsMetaCube’s C++ and OLE Interfaces . . . . . . . . . . . . 1-3Object Hierarchies . . . . . . . . . . . . . . . . . . 1-4

Collections . . . . . . . . . . . . . . . . . . . 1-5Parents and Children. . . . . . . . . . . . . . . . 1-5Inheritance . . . . . . . . . . . . . . . . . . . 1-8

Object Naming Restrictions . . . . . . . . . . . . . . . 1-9ValueList Objects . . . . . . . . . . . . . . . . . . 1-9Standard Data Types . . . . . . . . . . . . . . . . . 1-10Frequently Referenced Header Files . . . . . . . . . . . . 1-10

error.h . . . . . . . . . . . . . . . . . . . . . 1-10metacons.h . . . . . . . . . . . . . . . . . . . 1-10sdk.h . . . . . . . . . . . . . . . . . . . . . 1-11

Using the Get_m_ Functions . . . . . . . . . . . . . . 1-15

Chapter 2 Using the SDK Extension WizardSample Snap-In Extension . . . . . . . . . . . . . . . 2-3Generating a Template .cpp File . . . . . . . . . . . . . 2-4Editing Sample Code in the .cpp File . . . . . . . . . . . . 2-5

iv SDK f

Changing the Description of the Extension’s Arguments . . . 2-6Changing the Extension’s Argument Types . . . . . . . . 2-7Validating the Type and Value of All Arguments . . . . . . 2-9Creating the Process Code . . . . . . . . . . . . . 2-12Creating Multiple Extensions in a Snap-In . . . . . . . . 2-17

Building and Testing an Extension . . . . . . . . . . . . 2-19Sample Extension’s Code . . . . . . . . . . . . . . . 2-21

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

or Snap-Ins Programmer’s Manual

Summary . . . . . . . . . . . . . . . . . . . . . 3-286ValueList . . . . . . . . . . . . . . . . . . . . . 3-291

Index

Table of Contents v

vi SDK f
or Snap-Ins Programmer’s Manual

Introduction

Introduction

About This Manual . . . . . . . . . . . . . . . . . . . 3Organization of this Manual . . . . . . . . . . . . . . 3Types of User . . . . . . . . . . . . . . . . . . . 4

Documentation . . . . . . . . . . . . . . . . . . . . 5Printed Documentation . . . . . . . . . . . . . . . . 5

Typeface . . . . . . . . . . . . . . . . . . . . 6Online Help . . . . . . . . . . . . . . . . . . . . 7Readme Files . . . . . . . . . . . . . . . . . . . 7Related Reading . . . . . . . . . . . . . . . . . . 8

Compliance with Industry Standards . . . . . . . . . . . . 8

Informix Welcomes Your Comments . . . . . . . . . . . . . 9

2 SDK fo
r Snap-Ins Programmer’s Manual

This manual explains how to use the MetaCube C++ ApplicationProgramming Interface (API) and MetaCube’s SDK Extension Wizard tocreate custom Snap-In extensions to the analytical capabilities of MetaCubeExplorer and MetaCube for Excel.

About This ManualThe MetaCube SDK for Snap-Ins Programmer’s Manual contains information toassist you in developing extensions to the capabilities of the MetaCubeanalysis engine, such as a set of financial and analytical formulas that meetthe particular requirements of your organization. The SDK Extension Wizardcan generate code for a template Snap-In, which you can modify to meet yourneeds. After compiling and testing this code, your new extension can beeasily inserted, or “snapped into” MetaCube Explorer or MetaCube for Excel.

This manual explains some of the general concepts a programmer shouldunderstand when developing custom extensions to the MetaCube analysisengine, it explains how to use the SDK Extension Wizard, and it provides afull description of the class library that constitutes MetaCube’s C++ API.

Organization of this ManualThe chapters in this manual describe how to use MetaCube’s API and theSDK Extension Wizard to quickly create custom extensions. The manualincludes the following chapters.

■ This Introduction provides an overview of the manual

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

Introduction 3

Types of User

■ Chapter 2, “Using the SDK Extension Wizard,”explains theprocedure necessary to use a wizard to generate template code for anextension. It also describes how to modify that code so it can performthe calculations and changes required for your new extension.Finally it explains how to test the new extension and how to snap itinto MetaCube Explorer.

■ Chapter 3, “MetaCube Class Library,”details the entire contents ofMetaCube’s C++ API. It describes every MetaCube class accessiblethrough the SDK, and describes every member function and datamember within each class.

Types of UserThis manual is written for programmers who are developing custom exten-sions for MetaCube Explorer or MetaCube for Excel. You should beexperienced with Microsoft Visual C++, Microsoft Foundation Class (MFC)Libraries, Object Linking and Embedding (OLE) and the MicrosoftDeveloper Studio. You should also be familiar with MetaCube Explorer.

4 SDK for Snap-Ins Programmer’s Manual

Documentation

DocumentationMetaCube product documentation contains two key components:

■ printed documentation

■ online help

Printed DocumentationThe printed documentation for MetaCube products is divided into twodistinct types:

■ manuals for products with graphical user interfaces

■ manuals for application development tools

Manuals for products with user interfaces contain information about thevarious features of the product. This information is fairly high-level andconceptual in nature. These manuals are designed to give you informationabout the purpose of the product and what its capabilities are.

Manuals for application development tools are reference manuals thatprovide technical information about the tools.

In addition to this book, printed manuals for other MetaCube productsinclude the following:

■ MetaCube Explorer User’s Guide. This manual is written for peoplewho are responsible for analyzing data about their company’sbusiness. It describes the features of MetaCube Explorer for queryinga MetaCube data warehouse in multi-dimensional terms to obtainmeaningful reports that are the basis for timely business decisions.

■ MetaCube for Excel User’s Guide. This manual is written for peoplewho use Microsoft’s Excel spreadsheet for business analysis. Afteradding in MetaCube for Excel to the Excel software, an Excel usercan query a MetaCube data warehouse in multi-dimensional termsto obtain spreadsheet or PivotTable reports.

Introduction 5

Printed Documentation

■ MetaCube Warehouse Manager’s Guide. This manual is written for thedata warehouse administrator and describes how to specify internalinformation about the data warehouse so that the MetaCube compo-nents are able to access and graphically present the database forquerying.

■ MetaCube Data Warehouse Administrator’s Guide. This guide is writtenfor the data warehouse administrator. It describes the overall processof developing a data warehouse and it introduces the tools formanaging a data warehouse—MetaCube Secure Warehouse,MetaCube Agent Administrator, and MetaCube WarehouseOptimizer.

■ MetaCube Application Programmer’s Manual. This manual is writtenfor a programmer who will write custom applications that interactwith the MetaCube analysis engine. This manual describesMetaCube’s OLE Automation programming interface.

■ MetaCube SQL Optimizer User’s Guide. This manual describes how touse the MetaCube SQL Optimizer for connecting third-party querytools or custom query applications to the MetaCube analysis engineto access a MetaCube data warehouse. Queries are optimized to runagainst aggregate and sample tables, thereby significantlyimproving query performance against very large data warehouses.

■ MetaCube Installation and Configuration Guide. This manual describeshow to install and configure the MetaCube software components onboth 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 ofMetaCube components and some terms that are specific toMetaCube Web Explorer

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

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


Online Help

Online HelpEach MetaCube product that employs a graphical user interface includes anextensive online help system that provides step-by-step instructions on theuse of the product. The help system for most MetaCube products is accessedfrom 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 ona feature of the user interface. Selecting this menu option changes thecursor into a help cursor. Clicking a feature of the window with thehelp cursor displays help about that specific feature.

■ Help on Help: contains instructions on using the MetaCube onlinehelp. For the user unfamiliar with online help, this help systemexplains how to use the various features of MetaCube’s online helpsystem.

Context-sensitive help can be accessed by clicking the Help button on anapplication’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 onthe window’s Help menu.

In dialog boxes, pressing F1 displays a help topic that describes the featuresof that dialog box. From that topic, the user may jump to the main helpsystem or, in many cases, to a procedural help topic that describes how to usethe dialog box. In the main window of an application, after activating an areaof the window by clicking it, F1 provides a help topic that describes thatparticular area of the window.

Readme FilesIn addition to the printed manuals, readme files are distributed withMetaCube products. These files contain technical information, including last-minute changes to product capability or documentation. Please read thesefiles, as they contain important information.

Introduction 7

Related Reading

Related ReadingFor more information about Informix SQL, refer to the following Informixmanuals:

■ 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, byRalph Kimball (John Wiley & Sons, Inc., 1996).

Compliance with Industry StandardsThe American National Standards Institute (ANSI) has established a set ofindustry standards for SQL. Informix SQL-based products are fully compliantwith SQL-92 Entry Level (published as ANSI X3.135-1992), which is identicalto ISO 9075:1992, on Informix Dynamic Server. In addition, many featurescomply 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.


Informix Welcomes Your Comments

Informix Welcomes Your CommentsPlease tell us about our documentation. To help us with future versions of ourmanuals and online help, we want to know about any corrections or clarifi-cations that you would find 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 Publications300 Lakeside Drive, Suite 2700Oakland, 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


1Chapter

Basic Concepts

MetaCube’s C++ and OLE Interfaces. . . . . . . . . . . . . 1-3

Object Hierarchies . . . . . . . . . . . . . . . . . . . 1-4Collections . . . . . . . . . . . . . . . . . . . . 1-5Parents and Children . . . . . . . . . . . . . . . . . 1-5Inheritance . . . . . . . . . . . . . . . . . . . . 1-8

Object Naming Restrictions . . . . . . . . . . . . . . . . 1-9

ValueList Objects . . . . . . . . . . . . . . . . . . . 1-9

Standard Data Types . . . . . . . . . . . . . . . . . . 1-10

Frequently Referenced Header Files . . . . . . . . . . . . . 1-10error.h . . . . . . . . . . . . . . . . . . . . . . 1-10metacons.h . . . . . . . . . . . . . . . . . . . . 1-11sdk.h . . . . . . . . . . . . . . . . . . . . . . 1-12

Macros . . . . . . . . . . . . . . . . . . . . 1-12Buffer Sizes . . . . . . . . . . . . . . . . . . . 1-14Types . . . . . . . . . . . . . . . . . . . . . 1-15

Using the Get_m_ Functions . . . . . . . . . . . . . . . 1-16

1-2 SDK
for Snap-Ins Programmer’s Manual

This chapter discusses some basic concepts you should understandbefore using the MetaCube C++ programming interface to create your owncustom extensions to the MetaCube analysis engine. It explains therelationship between MetaCube’s C++ and OLE programming interfaces,describes the nature of MetaCube’s class hierarchy, details aspects of theapplication programming interface (API) that are commonly referenced, anddiscusses a C++ programming technique that may be unfamiliar to someusers.

MetaCube’s C++ and OLE InterfacesMetaCube consists of a library of object classes created in C++. To developcustom applications, such as modified versions of Explorer or MetaCube forExcel, MetaCube offers an OLE programming interface. With it, you can issuemessages in the form of OLE automation calls to MetaCube’s class library.MetaCube’s OLE programming interface is fully documented in theMetaCube Application Programmer’s Manual.

You can also develop custom extensions to the MetaCube engine itself. Forexample, you may want to create larger sets of statistical or financial formulasto analyze data. To make custom extensions, use MetaCube’s SDK ExtensionWizard and its C++ Application Programming Interface (API). Thisdocument, the MetaCube SDK for Snap-Ins Programmer’s Manual, explainshow to create custom extensions.

Basic Concepts 1-3

Object Hierarchies

Although many MetaCube classes support OLE automation calls, someclasses apply exclusively to the internal functionality of the MetaCubeanalysis engine. The names of all MetaCube classes that do not support OLEautomation begin with the letter C. Those classes are:

CDbCDimKeyCIExtensionCMetaObjectCOlapExceptionCOleCollectionCParseNodeCPlugInCQueryCubeCSelect

Some MetaCube classes, such as FactTable, Aggregate, and Dimension, areused exclusively for defining metadata rather than the analytic processes thatact on metadata. This manual does not describe these classes and the OLEautomation calls used to manipulate them, although Figure 2 on page 1-7does show the metadata classes and their relationship to the overallMetaCube hierarchy. For information on the metadata object classes, see theMetaCube Application Programmer’s Manual.

Object HierarchiesTo understand all of the relationships between the MetaCube classes, youshould be familiar with the following principles as they relate to theMetaCube C++ programming interface:

■ collections

■ parent/child relationships

■ inheritance

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

Collections

CollectionsIn 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 objectheld in that collection. For example, an object of the Queries class (note theplural name) holds a collection of Query objects (note the singular name).

In general, a collection of objects defines some aspect of the collection’sparent object. For example a Query object is the parent of a QueryItemscollection, and the QueryItem objects in that collection partially define thequery. Some types of objects, particularly Query and Metabase objects,contain multiple collections. A Query object, for example, contains collec-tions of MetaCube, QueryItem, QueryCategory, and Filter objects. Togetherthose collections define the query represented by the Query object.

Figure 1 on page 1-6 shows the hierarchical relationships between parentobjects and the collections that are their children. In that figure, note thatmost instances of a singular object are contained within a collection of likeobjects. For example, the QueryItems collection contains a QueryItem object;a Filters collection contains a Filter object.

Parents and ChildrenMost externally accessible MetaCube objects are arranged hierarchically. Anobject of the Metabase class is the master object in the hierarchy. Most of theother MetaCube objects are children, grandchildren, or great-grandchildrenof that Metabase object. Figure 1 on page 1-6 shows the hierarchical relation-ships between the MetaCube classes accessible through the SDKprogramming interface. For your reference, Figure 2 on page 1-7 shows allother MetaCube classes not directly accessible through the SDKprogramming interface. Note that Figure 1 and Figure 2 do not illustrateinheritance relationships between classes.

Except for CQueryCube, none of the internal classes of objects (those whosenames begin with “C”) are members of the MetaCube hierarchy of objectclasses. The internal classes provide particular types of functionality, or theyfunction as abstract base classes, described in “Inheritance” on page 1-8.

Basic Concepts 1-5

Parents and Children

Figure 1MetaCube Class Hierarchy Exposed Through API

RootFolder

Metabase

additional folders

QueryCategories

QueryCategory

QueryItems

QueryItem

Folders

Folder

Filters

Filter

FilterElements

FilterElement

QueryBackJobs

MetaCubes

MetaCube

Summaries

Summary

CQueryCube

QueryBackJob

ValueList

to any object derivedfrom COlapObject

Extensions

Extension

Queries

Query


Parents and Children

Figure 2MetaCube Class Hierarchy Not Exposed Through API

Tables

Table

FactTables

FactTable

Measures

Measure

Columns

Column

AggregateGrants

AggregateGrant

AggregateGroups

AggregateGroup

AggregateMeasures

AggregateMeasure

AggregateIndexes

AggregateIndex

to Metabase Object

DimensionElements

DimensionElements

Attributes

Attribute

DrillDataSources

FactTable

to Query Object

SystemMessages

SystemMessage

Schemas

Schema

Aggregates

Aggregate

Samples

Sample

SampleQualifiers

SampleQualifier

DimensionMappings

DimensionMapping

Users

User

Available DSSSystems

DSSSystem

DSSSystems

DSSSystem

Dimensions

Dimension

Basic Concepts 1-7

Inheritance

InheritanceAll MetaCube classes of objects are derived from existing classes of objects—either other MetaCube objects or objects in the Microsoft Foundation ClassLibrary. A derived class inherits the description of another class, known as abase class, but the derived class includes additional member variables andfunctions.

Three classes of MetaCube objects—COlapObject, CMetaObject, andCOleCollection—function as abstract base classes. These are classes that cannotbe instantiated but are used as a base class from which other classes arederived. For example, all MetaCube objects accessible through the SDKprogramming interface are derived from the COlapObject class. AllMetaCube 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 fromCOleCollection, which in turn is derived from COlapObject. AllCOlapObjects are derived from CCmdTarget and CObject. CCmdTarget isthe base class for the Microsoft Foundation Class Library message-maparchitecture. CObject is the principal base class for the entire MicrosoftFoundation Class Library.

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

Figure 3Hierarchy Chart for

the Queries ClassCObject

CCmdTarget

COlapObject

COleCollection

Queries


Object Naming Restrictions

Object Naming RestrictionsMetaCube imposes certain restrictions when defining an object name. Thestring 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:

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

Character Description

, comma

. period

" quotation mark

\t tab

\n new line

( left parenthesis

) right parenthesis

[ left bracket

] right bracket

' single quote

Basic Concepts 1-9

Standard Data Types

Standard Data TypesTo ensure that the data types used in the MetaCube class library havestandard lengths, the SDK programming interface employs only four types:

■ long (4 bytes)

■ double (8 bytes)

■ string (null-terminated)

■ Boolean

Frequently Referenced Header FilesThroughout the SDK’s programming interface, three header files arefrequently referenced:

■ error.h

■ metacons.h

■ sdk.h

error.hThe error.h file lists #define directives that assign a name and a code for allOLAP error messages. For an error that causes a COlapException object to bethrown, the member function COlapException::Get_m_code() returns areference to the appropriate code, as defined in error.h.


metacons.h

metacons.hThe metacons.h file defines external constants used by various memberfunctions throughout the SDK programming interface. At the appropriatelocations throughout Chapter 3, “MetaCube Class Library,” constants arelisted 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

■ Verification results

■ Format codes

Basic Concepts 1-11

sdk.h

sdk.hThe sdk.h file serves as the entry point for the header files generated by theSDK Extension Wizard. These header files contain all the class declarationsfor 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 byMicrosoft Visual C++. The sdk.h file also defines macros, buffers, and datatypes that may be useful when using the SDK programming interface. Theyare described in the following sections.

Macros

The sdk.h file defines the following macros that may be useful programmingtools 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 classand returns TRUE or FALSE.

IsA(objptr, type)

Parameters

objptr An object pointer

type The class being compared to the object pointer


sdk.h

DispIsA()

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

DispIsA(disp, type)

Parameters

MAKENULLS()

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

MAKENULLS(var1, var2, count)

Parameters

genclr()

Clears a specified amount of memory from a designated location.

genclr(ptr, sz)

Parameters

disp An IDispatch pointer

type The class being compared to the IDispatch pointer

var1 The location where nulls to be placed into the array are currentlystored

var2 The array where the nulls will be placed. This value is passed inas a parameter to a function such as CDb::ExecuteStmt().

count The number of items in the array

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 specified data type.

NULLP(type)

Parameters

NULLV()

Makes a null value of a specified data type.

NULLV(type)

Parameters

Buffer Sizes

The sdk.h defines four standard buffer sizes:

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

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

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


sdk.h

Types

The sdk.h defines three templated array types:

■ CLongArray—an array of long integers, defined with the followingstatement:typedef CArray<long, long&> CLongArray;

■ CDoubleArray—an array of doubles, defined with the followingstatement:typedef CArray<double, double&> CDoubleArray;

■ CKeyArray—an array of CDimKey objects, defined with thefollowing statement:typedef CArray<class CDimKey*, class CDimKey*> CKeyArray;

The sdk.h includes a struct data type called SCell, which defines the value ofeach cell in the QueryCube generated by processing a query. The SCell structappears 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 defined below:

cell_value A double containing the value of the cell

cell_format A CString containing the syntax used for formatting numeric datain different display environments. Typically cell formatting issupplied by the MetaCube Warehouse Manager, butQueryItem::SetFormatString() can be used to control the format ofcells 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 usedfor this query

Basic Concepts 1-15

Using the Get_m_ Functions

Using the Get_m_ FunctionsThroughout the SDK programming interface, many object classes includemember 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. Youcan 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, similarto a “get” member function, but the reference returned by a Get_m_ functioncan be changed, accomplishing the same effect as calling a “set” function.

Some MetaCube object classes include Get_m_ member functions thataccomplish essentially the same thing as related pairs of “get” and “set”member functions. Typically, the “get” and “set” functions return OLEhandles to objects or data types while the Get_m_ functions reference C++objects. For example, in the QueryCategory class, you can call GetName() toretrieve an OLE string containing the name of the QueryCategory object. Youcan call SetName() to change the name of the QueryCategory objectcontained in that OLE string. Similarly, you can call Get_m_name() toretrieve a CString containing the name of the QueryCategory object. Tochange the name of the QueryCategory object, you can change the value ofthe CString referenced by Get_m_name().


2Chapter

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-6Changing the Description of the Extension’s Arguments . . . . 2-6Changing the Extension’s Argument Types . . . . . . . . . 2-8Validating the Type and Value of All Arguments . . . . . . . 2-9

Understanding the Validate Function . . . . . . . . . . 2-11Creating the Process Code . . . . . . . . . . . . . . . 2-12

Understanding the Process Function . . . . . . . . . . 2-12Creating Multiple Extensions in a Snap-In . . . . . . . . . 2-17

Generating Headers for Multiple Extensions . . . . . . . 2-18Generating Functions for Multiple Extensions . . . . . . . 2-19

Building and Testing an Extension . . . . . . . . . . . . . 2-19

Sample Extension’s Code. . . . . . . . . . . . . . . . . 2-21

2-2 SDK

This chapter describes how to use the SDK Extension Wizard to createa .cpp file that contains template code for a MetaCube snap-in extension. Itexplains how to modify that template code to create your own customizedsnap-in extension or extensions. This chapter also describes how to build andtest a MetaCube Snap-In.

The procedures in this chapter describe the minimum changes necessary tocustomize a .cpp file so that it can successfully snap in to MetaCube Exploreror MetaCube for Excel. When creating your own Snap-Ins, use the MetaCubeAPI to modify a .cpp file in any way that best suits your needs.

Sample Snap-In ExtensionThroughout this chapter, a single example illustrates the process of using theSDK Extension Wizard. This sample extension calculates a harmonic movingaverage, which takes n number of values, multiplies those values together,and then derives the nth root of that number. Harmonic moving averages areuseful for deriving averages that discount the value of a few outlying datapoints.

The sample Snap-In is created in a Microsoft Developer Studio project called“harmonics.” The .cpp file generated for this example is namedharmonics.cpp. “Sample Extension’s Code” on page 2-21 shows the entireharmonics.cpp file after all modifications are complete.

Using the SDK Extension Wizard 2-3

Generating a Template .cpp File

Generating a Template .cpp FileThis section describes how to use the SDK Extension Wizard to generate atemplate .cpp file. The code that the Wizard automatically generates is afunctional extension that doubles the value of a measure. You must edit thiscode to implement the functionality you want for your own snap-inextensions.

Although the SDK Extension Wizard generates a template file that contains asingle extension, a Snap-In can contain multiple extensions. “CreatingMultiple Extensions in a Snap-In” on page 17 describes the proceduresnecessary 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 clickOK.

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 thesample extension, the workspace is named “harmonics.”

c. If necessary, type new information in the Platforms andLocation 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 introductorymaterial. After reading it, click Next. The dialog box associated withStep 2 of the SDK Extension Wizard is displayed.


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 arecreating. The sample extension is named “HarmonicMovingAvg.”The name you enter here will be used in the code that the SDKExtension 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 lowercase letters and underscores. Names longer than 25 characters maybe truncated when they are displayed in Explorer.

2. In the Extension Description box, type a description for theextension. Explorer and MetaCube for Excel present this text as adescription of the extension. For the sample extension, thedescription is “Harmonic moving average.”

3. In the Number of Arguments box, type in the number of argumentsneeded for the extension or click the arrows to specify a number. Thefirst argument identifies the measure on which the extensionoperates, so all extensions require at least one argument. For thesample 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.


Editing Sample Code in the .cpp File

Editing Sample Code in the .cpp FileAfter creating a project, you must edit the template code that the SDKExtension Wizard creates in the project_name.cpp file, where project_name isthe name you assigned when you created a new project workspace. Eachmain 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 APIto modify a .cpp file in any other way that suits your needs. Chapter 3,“MetaCube Class Library,” describes every class of object accessible throughthe 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 illus-trate the tasks you must perform. “Sample Extension’s Code” on page 2-21shows the complete file after it has been modified to create an extension thatcalculates a harmonic moving average.

In the .cpp file, the first function, DLLMAIN(), is automatically generated. Itis used for initializing a .dll file for this Snap-In. This function does notrequire any modification.

Changing the Description of the Extension’s ArgumentsIn a .cpp file, the first major function, extension_name_Arguments(), providesa description of the extension’s arguments. This description is stored in theString Table in a project’s resource file. After a Snap-In has been built andsuccessfully snapped into MetaCube Explorer, the description for eachargument is displayed in the Measure Calculation dialog box, where itprompts the user for input.


Changing the Description of the Extension’s Arguments

Every extension requires at least one argument that identifies a measure onwhich a calculation is performed. The SDK Extension Wizard automaticallygenerates template code providing a description of that argument. When anextension requires more than one argument, the SDK Extension Wizardgenerates template code that provides a default description for all additionalarguments.

The SDK Extension Wizard automatically generates a String Table that holdsa description for each of the extension’s arguments. Within the String Tablethose descriptions are called “captions.” The default caption for the secondand all subsequent arguments that the SDK Extension Wizard automaticallygenerates is “Argument.” To customize the description of an argument so itaccurately reflects the argument’s purpose, edit its caption in the String Table.For example, the caption for the second argument of the sample extensionwas changed from “Argument” to “Number of periods to harmonicallyaverage.” Limit the length of argument descriptions to 30 characters. If a textstring describing an argument exceeds this limit, it may be truncated whenExplorer displays it.

Figure 4 provides a fragment of code that shows the TODO commentflagging the change you must make to the descriptions of an extension’sarguments.

void harmonicmovingavg_Arguments(CStringArray& results){

results.RemoveAll();

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);

}

Figure 4ArgumentTypesFunction Before

Editing


Changing the Extension’s Argument Types

Changing the Extension’s Argument TypesIn a .cpp file, the second major function, extension_name_ArgumentTypes(),specifies argument types. You must correctly identify the type of eachargument needed for the extension you are creating.

The SDK Extension Wizard classifies all of the arguments it automaticallygenerates as Names, but five argument types are possible. The extensions.hfile for each project defines a constant for each of the possible argumenttypes. Figure 5 lists those definitions for your convenience:

The argument types do the following:

// 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"

Figure 5Argument Type

Constants

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. Forexample, a bucket that specifies a range requires a pair ofvalues: a lower bound and higher bound. Tuples should beentered 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 precedingaction should be performed


Validating the Type and Value of All Arguments

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

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

Validating the Type and Value of All ArgumentsIn the .cpp file, the third major function, extension_name_Validate(), checksthe data passed into the extension through its arguments. The code that isautomatically generated for a .cpp file validates the type and value of data forthe first argument. You should create code in the validate function to confirmthat the type of data passed in for the second and all subsequent argumentsis correct. For example, if an argument is a Number type, then you shouldwrite code that confirms that a number is passed in for that argument. Youmay also want to write code that checks the validity of all data that is passedin. For example, if an argument requires a number, you may want to confirmthat the number lies within an acceptable range.

void harmonicmovingavg_ArgumentTypes(CStringArray& results){

results.RemoveAll();results.Add(EXT_ARG_NAME);

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

results.Add(EXT_ARG_NAME);}

Figure 6ArgumentTypesFunction Before

Editing


results.RemoveAll();results.Add(EXT_ARG_NAME);results.Add(EXT_ARG_NUMBER);

}

Figure 7ArgumentTypes

Function AfterEditing



Figure 8 provides a fragment of code that shows the TODO commentflagging the validate function:

Figure 8Validate Function

BOOL harmonicmovingavg_Validate(class Query* query, class COlapObject* obj, class CParseNode* parse){

// Setupclass 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;

}



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

Understanding the Validate Function

The validate function in the .cpp file takes three arguments: query, obj, andparse. The first argument identifies the Query object that contains theextension. The second argument specifies the QueryItem object that calls thisextension. The last argument points to a CParseNode object, which providesthe 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. TheCParseNode objects on the next level in the tree are children of the parentCParseNode object. Each child object on this level corresponds to one of theextension’s arguments. If those arguments consist of function calls,additional levels of CParseNode objects are necessary to represent thosefunction calls.

The validate function checks how many child objects of the parentCParseNode object have been passed to the extension. That number mustmatch the number of arguments specified for the extension. In the sampleextension, two arguments are specified, so the validate function includes thefollowing code that confirms the presence of two CParseNode child objects:


//*** checked that 2nd arg is a numberif (arg->m_type != CParseNode::NumberType)

return FALSE;

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

return FALSE;

Figure 9Lines Inserted into

the ValidateFunction


Creating the Process Code

Next the validate function checks the type of the first argument. The firstargument may specify a query item that is a measure (in other words, a datavalue from a fact table, such as Units Sold), or it may include a recursivefunction call, such as a computation of a harmonic moving average or apercent change. The validate function confirms that the first argument iseither a name, such as the name of a measure, or a function call. To performthis 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 otherarguments to validate their type and value using the code you have writtenfor that purpose.

Creating the Process CodeIn the .cpp file, the process function, extension_name_Process(), does theactual work of an extension, performing calculations and changes on existingdata and creating new values based on that data. The process function that iscreated automatically by the SDK Extension Wizard doubles the value of acell. You must modify that code to create the functionality needed for yourown extension. In the sample extension, the harmonic moving average iscalculated for a number of periods specified by the user.

Understanding the Process Function

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



The first and outermost loop in the process function walks all the pages in thevirtual cube of data, determining the size of the page and the direction inwhich query items appear. Query items can be arranged on a page usingeither a column or row orientation. Figure 10 shows the loop in the .cpp filethat walks the pages:

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

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;

elsemax_dist = rows;

.

.

.}

Figure 10Loop Walking the

Pages in theProcess Function

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);

elseqcube->GetCellItemIndex(page, location, 0, cell_index);

.

.

.}

Figure 11Loop Walking the

Row/Column in theProcess Function



The third loop walks every cell in a row or column and processes the datastored in that cell. Before the loop starts, an if statement performs a test todetermine whether the query item for that row or column is one on whichthis 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 orcolumn is not one on which the extension should operate—the processfunction skips that row or column. If the expression is true, the functionwalks the cells in that row or column, gets the value in each cell, performs thedesired change or calculation, and puts a new value back into that cell.Typically, when you are customizing a .cpp file, this is the code that you willmodify most extensively. It performs the work of your extension.

Figure 12 shows code that the SDK Extension Wizard inserts into the .cpp filebefore the beginning of the third loop. This code includes the if statementtesting the query item. Note that for the sample extension, code has beeninserted here to declare two CArrays.

// 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;

elsewalk_dist = columns;

// Walk the cells and process them...

long position;

//*** storage for the cells to be averagedCArray<double, double&> harmonic_cells;CArray<double, double&> harmonic_cells_errors;

Figure 12Code Before the

Third Loop Begins



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

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

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);

elseqcube->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 13Beginning of the

Third Loop



Figure 14Process 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 manyif (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;


Creating Multiple Extensions in a Snap-In

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

Creating Multiple Extensions in a Snap-InA Snap-In can consist of multiple extensions. The template code generated bythe SDK Extension Wizard creates one extension, but you can customize thatcode so it includes multiple extensions. To accomplish this, do the following:

■ Generate multiple headers

■ Generate parallel functions for each extension

// 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);

elseqcube->SetCell(page, location, position, new_value);

}

Figure 15Close of Third Loop

That Inserts NewValues Into Virtual

Cube of Data


Creating Multiple Extensions in a Snap-In

Generating Headers for Multiple Extensions

Header information for an extension appears at the end of the .cpp file. If thefile contains only one extension, the header information that was automati-cally generated by the SDK Extension Wizard is correct. Figure 16 shows theheader block for the sample extension:

If the .cpp file contains multiple extensions, you must create an additionalheader block for each extension. To do that, copy and paste the lines shownabove and edit the data in those lines to match each of the additional exten-sions. Figure 16 shows a header block that has been created for a secondextension called “statmove”:

// 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";

// 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;

Figure 16Header Block for

Sample Extension


// HarmonicMovingAvg - QueryItem...

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

// Set up the headerstatmove_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;

Figure 17Header Block for

Second Extension


Building and Testing an Extension

Generating Functions for Multiple Extensions

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

Building and Testing an ExtensionWhen you have finished writing the code for a .cpp file, use MicrosoftDeveloper Studio to build and test an .mcx file, which represents the actualSnap-In. The following procedures describe the steps necessary for buildingand testing an .mcx file.

To build a pre-release .mcx file:

1. Use the drop-down list on Microsoft Developer Studio’s toolbar toset the default project configuration. The drop-down list includestwo options: Win32 Debug or Win32 Release. While testing a Snap-In, set the project configuration 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 andfile name of the executable code for the target application and thenclick OK. For example, if you want run the new extension inMetaCube Explorer, enter a path to Explorer’s executable code, suchas c:\MetaCube\expl32.exe. If you want to run the new extension inMetaCube for Excel, enter a path to Excel’s executable.

Note: You cannot use MetaCube Web Explorer to debug newextensions.


Building and Testing an Extension

4. Click Go. Microsoft Developer Studio runs the targeted applicationand the MetaCube analysis engine within the Developer Studio’sdebugging environment.

To snap an extension into Explorer:

1. Invoke MetaCube as described above. Then start Explorer, whichwill connect to the instance of MetaCube running in the DeveloperStudio’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 clickOK.

To test and debug an extension:

1. After invoking Explorer within the Microsoft debuggingenvironment, run a query that uses the new extension. For moreinformation on creating queries, see the MetaCube Explorer User’sGuide.

2. Verify the results generated by the new query.

If software problems exist, modify the extension’s functionality in the .cppfile, re-compile the file, and test it again in Explorer. After an extension hasbeen 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 thedefault project configuration to Win32 Release. Build the project, whichgenerates a new .mcx file, and the new extension is ready for release.


Sample Extension’s Code

Sample Extension’s CodeThis section shows the complete text of the final harmonics.cpp file. All thecode 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 heavygray bar ( ) to the left of that line.

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

#include "stdafx.h"#include <afxdllx.h>#include <math.h>

#ifdef _DEBUG#define new DEBUG_NEW#undef THIS_FILEstatic char THIS_FILE[] = __FILE__;#endif

static AFX_EXTENSION_MODULE HarmonicsDLL = { NULL, NULL };

extern "C" int APIENTRYDllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved){

if (dwReason == DLL_PROCESS_ATTACH){

TRACE0("HARMONICS.DLL Initializing!\n");

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

// Insert this DLL into the resource chainnew CDynLinkLibrary(HarmonicsDLL);

}else if (dwReason == DLL_PROCESS_DETACH){

TRACE0("HARMONICS.DLL Terminating!\n");}return 1; // ok

}



void harmonicmovingavg_Arguments(CStringArray& results){

results.RemoveAll();

CString buf;

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

}


results.RemoveAll();results.Add(EXT_ARG_NAME);//*** changed type from name to numberresults.Add(EXT_ARG_NUMBER);

}

BOOL harmonicmovingavg_Validate(class Query* query, class COlapObject* obj, class CParseNode* parse){

// Setupclass Metabase* metabase = query->Get_m_metabase();

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


// 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 numberif (arg->m_type != CParseNode::NumberType)

return FALSE;

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

return FALSE;}

return TRUE;}



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...



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





for (long location = 0; location < max_dist; ++location){

// Now, walk and look for our row/column...

long 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;

elsewalk_dist = columns;

// Walk the cells and process them...

long position;

//*** storage for the cells to be averagedCArray<double, double&> harmonic_cells;CArray<double, double&> harmonic_cells_errors;

for (position = 0; position < walk_dist; ++position){


// Get the cell...



double old_val = 0;double old_error = 0;

if (cell_val){

old_val = cell_val->cell_value;old_error = cell_val->cell_error;

}



//*** 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 manyif (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;



// Now, put it back...

SCell new_value;

// Preserve the formatting...if (cell_val)

new_value = *cell_val;






}}

}}

}

// 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;


// 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;

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

}


3Chapter

MetaCube Class LibraryReference

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

3-2 SDK

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


This chapter describes the MetaCube class library that is accessiblethrough the SDK. For every class, this chapter provides a hierarchy chart, asummary list of the possible member functions and data members, and adetailed description of each member function and data member.

CDb

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

CObject

CDb

MetaCube Class Library 3-3

CDb Class Members

CDb Class Members

Operations

Commit Confirms changes that have been made to a database (if thedatabase has logging turned on)

DeleteString Deletes a string stored by PutString()

EndSelect Destroys the CSelect object created by the SelectStmt() memberfunction

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

GetColumns Retrieves information about tables owned by a particular user ina 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 thetables owned by a particular user or schema in the database

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

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

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

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


CDb::Commit

CDb::Commitvoid Commit();

Remarks

Call this member function to confirm changes that have been made to adatabase. If a database does not have logging turned on, changes made tothat database take effect as soon as a statement executes. For those types ofdatabases, the Commit() function is unnecessary.

CDb::DeleteStringvoid DeleteString( long msgid );

Parameters

Remarks

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

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


CDb::EndSelect

CDb::EndSelectvoid EndSelect( CSelect* select );

Parameters

Remarks

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

select Specifies the CSelect object to be destroyed.


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

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

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

Parameters

Remarks

Call this member function to execute a non-SELECT SQL statement, such asCREATE 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 runtimearguments)” on page 3-8. To execute an SQL SELECT statement, see“CDb::SelectStmt” on page 3-16.

stmt A character string that provides the SQL statement to beexecuted.

nrows An optional argument that points to the number of rows thatwere processed by the SQL statement, such as the number ofrows that were deleted. If a value is not defined for nrows, itdefaults to a null pointer.


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 boundinto the SQL statement (that is, the number of question marks theSQL statement employs). The following example shows an SQLstatement that requires two arguments:

INSERT INTO EMP VALUES (?, ?)

The number specified for nbinds determines the number of valuesthat must be passed in for the types, values, sizes, and nullsarguments. For example, if nbinds equals three, the length of thearray for the types, values, sizes, and nulls arguments must be three.

types A pointer to a long integer or an array of constants specifying thedata type for an argument. The cdb.h file defines a name andconstant for each of the possible data types. They are:

Name Constant Data Type

DB_CHARDB_NUMDB_FLOATDB_DOUBLE

1234

char*longfloatdouble

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

sizes An optional argument providing an array of integers used tospecify the size of strings. If the size specified with this argumentis smaller than the string actually placed into an array, the stringwill be truncated.


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

Remarks

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

nulls An optional argument providing an array of pointers to constantsthat provide null flags. Null flags designate values as null values ornot null values. A null flag causes the values stored in the arraysspecified with the values argument to be ignored and to be replacedby null. The null flag takes precedence over a value stored in thearrays specified with the values argument. The sdk.h file includes amacro 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_NULLDB_NNULL

-1-3

SQL_NULL_DATASQL_NTS

iters A long integer specifying the number of iterations for thisstatement. By inserting arrays of values for the types, values, sizes,and nulls parameters, ExecuteStmt() can run repeatedly, insertingthe next set of values from the appropriate array every time itexecutes. The default value for iters is 1.

nrows An optional argument pointing to the number of rows that wereprocessed by the SQL statement. If a value is not defined for nrows,it defaults to a null pointer.


CDb::GetColumns

CDb::GetColumnsvoid GetColumns( CString& schema, CString& table,

CStringArray& results, CLongArray& types, long maxrows = 1000 );

Parameters

Remarks

Call this member function to retrieve information about a table owned by aparticular user or schema in the database. This function points references toarrays filled with the names of a table’s columns and the data type for eachcolumn.

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

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

results A reference to an array of CString objects that will be filled with thenames of the columns in the table specified with the schema andtable arguments.

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



1234


maxrows The maximum size allowed for the array specified with the resultsargument. If not specified, the maximum is 1000 rows.


CDb::GetDataSources

CDb::GetDataSourcesvoid GetDataSources( CStringArray& results,

long maxrows = 1000 );

Parameters

Remarks

Call this member function to retrieve information about ODBC datasources.This function retrieves references to arrays filled with the names of ODBCdatasources configured for the computer where the MetaCube analysisengine is running.

results A reference to an array of CString objects that will be filled with theODBC datasource names configured for the computer where theMetaCube analysis engine is running.



CDb::GetString

CDb::GetStringvoid GetString( long msgid, CString& str );

Parameters

Remarks

Call GetString() to point a reference to a string stored by PutString().

The Informix database limits column lengths. For example, character-typecolumns are limited to 2,000 characters. To avoid this limitation and storestrings of any arbitrary size, use the PutString() and GetString() memberfunctions.

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

str A reference that returns a CString filled with the string stored bythe PutString() member function


CDb::GetTables

CDb::GetTablesvoid GetTables( CString& schema, CStringArray& results,

long maxrows = 1000 );

Parameters

Remarks

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

schema A reference to a CString containing the name of the schema oruser returned by GetUsers().

results A reference that returns an array of CString objects filled withnames of the tables grouped with the user or schema specified bythe schema argument.



CDb::GetUsers

CDb::GetUsersvoid GetUsers( CStringArray& results, long maxrows = 1000 );

Parameters

Remarks

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

results A reference that returns an array of CString objects filled with thenames of the users or schemas in the database.



CDb::PutString

CDb::PutStringlong PutString( CString& str );

Return Value

A long integer identifying a string that has been stored.

Parameters

Remarks

Call PutString() to store a string of any size. The member function returns anidentifying integer for the string it stores. Call GetString() to point a referenceto the string stored with PutString().

The Informix database limits column lengths. For example, character-typecolumns are limited to 2,000 characters. To avoid this limitation, use thePutString() and GetString() member functions.

CDb::Rollbackvoid Rollback();

Remarks

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

str A reference to a string of any length


CDb::SelectStmt

CDb::SelectStmtCSelect* 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 boundinto the SQL statement (that is, the number of question marks theSQL statement employs). The number specified for nbinds deter-mines the number of values that must be passed in for the types,values, and sizes arguments. For example, if nbinds equals three, thelength of the array for the types, values, and sizes arguments must bethree.

types A pointer to an array of constants specifying the data types for anargument. The cdb.h file defines a name and constant for each ofthe possible data types. They are:



1234


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 specifya string.

rows A long integer that specifies how many rows at a time should beretrieved. If not specified, the default value for this argument is 1row.


CDb::SelectStmt

Remarks

Call this member function to execute an SQL statement that performs a query,returning values or other information. The SQL statement submitted withthis member function can require runtime arguments. When SelectStmt() isexecuted, it returns a handle to a CSelect object, from which the results of thequery can be obtained using the CSelect member functions. After you haveobtained 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 thatperforms a query, see “CDb::ExecuteStmt (for non-SELECT SQL syntaxrequiring no runtime arguments)” on page 7 or “CDb::ExecuteStmt (for non-SELECT SQL syntax requiring runtime arguments)” on page 8.

sizes An optional argument providing an array of integers used tochange the size of strings. By default, character strings are null-terminated, longs are 4 bytes, floats are 4 bytes, and doubles are 8bytes. If the size specified with this argument is too small for astring put into an array, the string will be truncated.

Query An optional argument providing a pointer to the Query object forthe query that is being performed. Specifying a pointer with thisargument is necessary if the query is asynchronous and theasynchronous query may have to be canceled. If this argument isnot specified, its default value is a macro generating a null pointer.


CDimKey

CDimKey

A QueryCube is a multi-dimensional cube of data. Data points within thecube store values for the query’s measures. Along the various axes of thecube are points known as dimension keys. Each CDimKey object representsa dimension key. For example, on a QueryCube dimension that providesbrand information, each different brand, such as Alden, Barton, or Delmore,is a dimension key, and each would be represented by a different CDimKeyobject.

Dimension keys can be sorted alphabetically or they can use numeric sortingschemes. Dimension keys can also be grouped. Within each group, thedimension keys are sorted using either an alphabetic or numeric scheme.

CObject

CDimKey


CDimKey Class Members

CDimKey Class Members

Operations

CDimKey Constructs a CDimKey object using two possible techniques:one requires you to supply arguments that define the CDimKeyobject; the other is a copy constructor that copies the value ofone CDimKey object to create a new CDimKey object.

Hash Returns a number for a CDimKey object that is almost certainlyunique and can be used for quick comparisons

operator> Determines if a CDimKey object is greater than this CDimKeyobject

operator< Determines if a CDimKey object is less than this CDimKeyobject

operator== Determines if a CDimKey object is equal to this CDimKey object

SetFrom Sets the value of an existing CDimKey object by using the valueof 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 thevalue of m_string or m_sortval

m_sortval Provides a numeric value that is used to sort dimension keyswhen m_selfsort is zero

m_string Provides a string representation (typically the name) of thevalue of a dimension key


CDimKey::CDimKey

CDimKey::CDimKeyCDimKey ( LPCTSTR string, long group = 0,

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

Parameters

Remarks

Call either of these constructor member functions to construct a CDimKeyobject. One version of CDimKey() requires you to supply arguments thatdefine the CDimKey object. The other version of CDimKey() is a copyconstructor that copies the value of one CDimKey object to create a newCDimKey object.

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

group An optional argument providing a value for m_group for aCDimKey object. If no value is specified for this argument, thevalue of m_group for this CDimKey object will default to 0.

selfsort An optional argument specifying a value for m_selfsort for aCDimKey object. If no value is specified for this argument, thevalue of m_selfsort for this CDimKey object will default to TRUE.

sortval An optional argument specifying a numeric sorting value for aCDimKey object. If no value is specified for this argument, thevalue of m_sortval for this CDimKey object will default to 0.

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


CDimKey::Hash

CDimKey::HashUINT Hash();

Return Value

An unsigned integer.

Remarks

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

CDimKey::m_grouplong m_group;

Remarks

This data member assigns a numeric value that is used to group dimensionkeys. For example, if the Brand attribute is assigned a value of 1 and all otherProduct attributes are assigned a value of 2, all Brand data points are listedon a QueryCube axis first and then all other Product data points are listedsecond. Within each group, dimension keys are sorted using the methodspecified by the m_selfsort data member.


CDimKey::m_selfsort

CDimKey::m_selfsortBool m_selfsort;

Remarks

This data member provides a Boolean value. Nonzero indicates thatdimension 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 them_sortval data member.

CDimKey::m_sortvallong m_sortval;

Remarks

This data member provides a numeric value that is used to sort dimensionkeys when m_selfsort is set to zero.

In MetaCube Warehouse Manager, you can specify a numeric column whosevalues are used to sort corresponding attribute values. For example, acolumn 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 chronologicalorder. If a column of numeric values is used for sorting attribute values, eachparticular number is assigned to a CDimKey object using the m_sortval datamember.


CDimKey::m_string

CDimKey::m_stringCString m_string;

Remarks

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


CDimKey::operator>

CDimKey::operator>BOOL operator>( CDimKey& operand );

Return Value

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

Parameters

Remarks

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

Example

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

operand A reference to a CDimKey object


CDimKey::operator<

CDimKey::operator<BOOL operator<( CDimKey& operand );

Return Value

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

Parameters

Remarks

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

Example

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



CDimKey::operator==

CDimKey::operator==BOOL operator==( CDimKey& operand );

Return Value

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

Parameters

Remarks

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

Example

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



CDimKey::SetFrom

CDimKey::SetFromvoid SetFrom( CDimKey& source );

Parameters

Remarks

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

source A reference to a CDimKey object


CIExtension

CIExtension

A CIExtension object describes one of the extensions in a Snap-In (an .mcxfile) to the MetaCube engine. The .cpp file used to create a Snap-In shouldcontain a header block of code identifying each extension included in theSnap-In. That header block creates a CIExtension object for each extension inthe Snap-In and hands that CIExtension object to the MetaCube engine.

Do not confuse a CIExtension object with an Extension object. An Extensionobject embodies a Snap-In (an .mcx file) while a CIExtension object representsa 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 .cppfile for a Snap-In

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

m_name Provides the name of an extension

m_processitem Provides a pointer to an extension_name_Process() function inthe .cpp file for a Snap-In

m_validate Provides a pointer to an extension_name_Validate() function inthe .cpp file for a Snap-In

CObject

CIExtension


CIExtension::m_arguments

CIExtension::m_argumentsvoid (*m_arguments)(CStringArray& results);

Parameters

Remarks

This data member points a reference to an extension_name_Arguments()function in the .cpp file for a Snap-In, where extension_name is the nameassigned to an extension with the SDK Extension Wizard. Theextension_name_Arguments() function provides descriptions of all thearguments needed for an extension. Those descriptions are typically storedin the String Table in a project’s resource file.

results A reference to the CStringArray to be filled in by theextension_name_Arguments() function in the .cpp file for thisSnap-In


CIExtension::m_argumenttypes

CIExtension::m_argumenttypesvoid (*m_argumenttypes)(CStringArray& results);

Parameters

Remarks

This data member points a reference to an extension_name_ArgumentTypes()function in the .cpp file for a Snap-In, where extension_name is the nameassigned to an extension with the SDK Extension Wizard. Theextension_name_ArgumentTypes() function classifies the types of all thearguments needed for an extension.

CIExtension::m_nameCString m_name;

Remarks

This data member is a CString that provides the name of an extension. Thename is assigned when you invoke the SDK Extension Wizard to create a .cppfile.

results A reference to the CStringArray to be filled in by theextension_name_ArgumentTypes() function in the .cpp file for thisSnap-In


CIExtension::m_processitem

CIExtension::m_processitemvoid (*m_processitem)(class Query* query,

class QueryItem* item, class CParseNode* parse);

Parameters

Remarks

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

CIExtension::m_typeenum {QueryCategoryType, QueryItemType} m_type;

Remarks

This data member is an enumerated type, which provides a flag indicatingwhether an extension performs its function on a QueryItem or a QueryCat-egory object.

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

item The pointer to the QueryItem representing the measure on whichthis extension operates

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


CIExtension::m_validate

CIExtension::m_validateBOOL (*m_validate)(class Query* query,

class COlapObject* obj, class CParseNode* parse);

Return Value

A Boolean value. Nonzero indicates the data passed into an extensionthrough its arguments is valid. Zero indicates that the data passed in is notvalid.

Parameters

Remarks

This data member stores a pointer to an extension_name_Validate() function inthe .cpp file for a Snap-In, where extension_name is the name assigned to anextension with the SDK Extension Wizard. The extension_name_Validate()function confirms that the data passed into an extension through itsarguments is valid.

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

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

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


CMetaObject

CMetaObject

The CMetaObject class functions as an abstract base class for many otherMetaCube classes but cannot be instantiated itself. The CMetaObject classprovides many of the common characteristics of the objects that are itschildren. You can call CMetaObject member functions for any objectsdescended from a CMetaObject object.

All of the object classes that define a metamodel, such as Attributes, Dimen-sions, DimensionElement, and FactTable, are children of the CMetaObjectclass. Of the object classes accessible through the SDK programminginterface, the CMetaObject class serves as a parent for the following:

■ Metabase

■ Filter

■ FilterElement

CObject

CCmdTarget

COlapObject

CMetaObject


CMetaObject Class Members

CMetaObject Class Members

Operations

GetDirty Determines if an object’s definition that is stored in metadatahas changed since the object was last saved

GetVerified Retrieves the verification results returned by Verify() withoutcalling that member function again

GetVerifyResults Retrieves a pointer to the ValueList object created by calling theVerify() function. That ValueList object contains any messagesgenerated during the verification process.

Verify Reviews the validity of the metadata definitions represented byan object and any other objects within that object’s collectionsand sub-collections


CMetaObject::GetDirty

CMetaObject::GetDirtyBOOL GetDirty();

Return Value

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

Remarks

Call this member function to determine if the definition of an object that isstored in metadata has changed since the object was last saved.


CMetaObject::GetVerified

CMetaObject::GetVerifiedlong GetVerified()

Return Value

A integer that shows the verification results returned the last time Verify()was called.

Remarks

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

Filter Element Type Name in Metacons.h Constant

Object has never been verified VerifiedNever 0

Object verified successfully VerifiedGood 1

Object itself verifies, but otherobjects in its collections orsub-collections do not

VerifiedBadBelow 2

Object itself fails to verify VerifiedBad 3


CMetaObject::GetVerifyResults

CMetaObject::GetVerifyResultsLPDISPATCH GetVerifyResults();

Return Value

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

Remarks

Call this member function to retrieve a pointer to a ValueList object createdby calling the Verify() function. This ValueList object contains any messagesgenerated while the Verify() function checked the validity of the metadatadefinitions represented by an object and any other objects within that object’scollections and sub-collections.


CMetaObject::Verify

CMetaObject::Verifylong Verify()

Return Value

A integer that represents verification results.

Remarks

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


Object has never been verified VerifiedNever 0

Object verified successfully VerifiedGood 1

Object itself verifies, but otherobjects in its collections orsub-collections do not

VerifiedBadBelow 2

Object itself fails to verify VerifiedBad 3


COlapException

COlapException

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

COlapException Class Members

Operations

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

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

CObject

CException

COlapException


COlapException::Get_m_code

COlapException::Get_m_codeWORD& Get_m_code();

Return Value

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

Remarks

Call this member function to retrieve the code for the error that caused thisCOlapException object to be thrown. The error.h file lists constants for all thepossible OLAP errors.

COlapException::Get_m_reasonCString& 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 theerror that caused this COlapException object to be thrown. The MetaCubeengine generates an appropriate text string for each error.


COlapObject

COlapObject

The COlapObject class functions as an abstract base class for all otherMetaCube classes but cannot be instantiated itself. The COlapObject classprovides characteristics that are common to all MetaCube objects. You cancall 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 thisobject

Get_m_metabase Retrieves the Metabase object

GetApplication Returns a pointer identifying the application, the MetaCubeengine

GetParent Retrieves an IDispatch pointer to the parent object for thisobject

GetRefCount Retrieves the OLE reference count associated with the object

GetType Returns a string identifying the class to which an objectbelongs

CObject

CCmdTarget

COlapObject


COlapObject::Get_m_application

COlapObject::Get_m_applicationLPDISPATCH& Get_m_application();

Return Value

A reference to an IDispatch pointer that identifies the MetaCube engine.

Remarks

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

COlapObject::Get_m_iparentclass 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 parentobject for this object.


COlapObject::Get_m_metabase

COlapObject::Get_m_metabaseclass Metabase*& Get_m_metabase()

Return Value

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

Remarks

Call this member function to retrieve the Metabase object. For everyMetaCube procedure, a Metabase object is the master object, with all otherobjects existing as children, grandchildren, great-grandchildren, and so forthof this master object.

COlapObject::GetApplicationLPDISPATCH GetApplication();

Return Value

An IDispatch pointer that identifies the MetaCube engine.

Remarks

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


COlapObject::GetParent

COlapObject::GetParentLPDISPATCH GetParent()

Return Value

An IDispatch pointer that identifies the parent object for this object.

Remarks

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

COlapObject::GetRefCountlong GetRefCount()

Return Value

A long integer that is the OLE reference count.

Remarks

Call this member function to retrieve the OLE reference count associatedwith an object. This is a read-only function that is typically used fordebugging purposes.


COlapObject::GetType

COlapObject::GetTypeBSTR 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. Forexample, if an object belongs to the Filter class, the string that is returnedcontains “Filter”.


COleCollection

COleCollection

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

CObject

CCmdTarget

COlapObject

COleCollection


COleCollection Class Members


Operations

AddItem Adds an object to a collection and puts the object at the endof the collection

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

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

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

GetItem Retrieves an IDispatch pointer to an object in a collection

GetNames Retrieves an IDispatch pointer to a ValueList objectcontaining 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 specified objecttakes a designated position in the collection

IRemoveAll Removes all objects from a collection

MakeFirst Rearranges the order of objects in a collection so thespecified object becomes the first item

MakeLast Rearranges the order of objects in a collection so thespecified object becomes the last item

MakeNth Rearranges a collection of objects so the specified objecttakes a designated position in the collection

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



RemoveItem Removes an object from the collection of objects. The objectto be removed can be specified by a number or a constantthat can be either a name or a number.

RemoveAll Removes all objects from a collection and calls the OLErelease function

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

Operations


COleCollection::AddItem

COleCollection::AddItemvoid AddItem( LPDISPATCH element );

Parameters

Remarks

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

COleCollection::Get_m_countlong& Get_m_count()

Return Value

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

Remarks

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

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


COleCollection::GetCount

COleCollection::GetCountlong 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::GetElementIndexlong GetElementIndex( LPDISPATCH element )

Return Value

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

Parameters

Remarks

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

element The IDispatch pointer to an object.


COleCollection::GetItem

COleCollection::GetItemLPDISPATCH GetItem( const VARIANT FAR& index )

Return Value

An IDispatch pointer to an object in a collection.

Parameters

Remarks

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

COleCollection::GetNamesLPDISPATCH GetNames()

Return Value

The IDispatch pointer associated with a ValueList object containing objectnames.

Remarks

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

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


COleCollection::IGetItem

COleCollection::IGetItemclass 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

Remarks

Call this member function to retrieve a pointer to a MetaCube object derivedfrom the COlapObject class. Three versions of this member function exist. Allproduce the same result but allow you to use different methods to identifythe object to be retrieved.

index The index representing the object to be retrieved. The index can bespecified with any of the following:

■ A constant representing the object. The index constant can bea long integer (the 0-based index of the object) or a string (thename of the object).

■ The 0-based index of the object

■ A reference to a CString object containing a name


COleCollection::IMakeNth

COleCollection::IMakeNthvoid IMakeNth( long index, long n );

Parameters

Remarks

Call this member function to rearrange a collection of objects so the specifiedobject takes a designated position in the collection.

COleCollection::IRemoveAllvoid IRemoveAll();

Remarks

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

index The 0-based index of the object to be moved

n A number specifying the new position for the object to be moved


COleCollection::MakeFirst

COleCollection::MakeFirstvoid MakeFirst( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of objects in a collection soa specified object becomes the first item.

COleCollection::MakeLastvoid MakeLast( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of objects in a collection soa specified object becomes the last item.

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

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


COleCollection::MakeNth

COleCollection::MakeNthvoid MakeNth( const VARIANT FAR& index, long n );

Parameters

Remarks

Call this member function to rearrange a collection of objects so the specifiedobject takes a designated position in the collection.

COleCollection::Removevirtual void Remove( const VARIANT FAR& index ) = 0;

Parameters

Remarks

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

index A constant representing the object to be moved within thecollection of objects. The index constant can be an integer (the0-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

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


COleCollection::RemoveAll

COleCollection::RemoveAllvoid RemoveAll( BOOL release = FALSE );

Parameters

Remarks

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

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


COleCollection::RemoveItem

COleCollection::RemoveItemLPDISPATCH RemoveItem( const VARIANT FAR& index );LPDISPATCH RemoveItem( long index );

Return Value

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

Parameters

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 collectionclasses, this member function returns a handle to the object being removed.

index The index representing the object to be removed. The index can bespecified with any of the following:

■ A constant representing the object. The index constant can bean integer (the 0-based index of the object) or a string (the nameof the object).

■ The 0-based index of the object


COleCollection::Swap

COleCollection::Swapvoid Swap( const VARIANT FAR& index1,

const VARIANT FAR& index2 );

Parameters

Remarks

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

index1 A constant representing the object whose position will beswapped within the collection of objects. The index constant canbe an integer (the 0-based index of the object) or a string (the nameof the object).

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


CParseNode

CParseNode

Every CParseNode object provides pieces of information about an extensioncall. Using parent/child relationships, CParseNode objects form hierarchicaltree structures, with each object representing a node in the tree. A tree ofCParseNode objects collectively provides all the information necessary toprocess or validate an extension. MetaCube generates all CParseNodeobjects, and they should require no additional modification.

For each CParseNode object, data members provide the following pieces ofinformation:

■ Type: The m_type data member defines an object as one of thefollowing:

❑ NameType: CParseNode object has a string value and nochildren

❑ NumberType: CParseNode object has a number value and nochildren

❑ TupleType: CParseNode object has two children but no string ornumber value

❑ FunctionType: CParseNode object has a string value thatcontains a function call and a child object representing each ofthe arguments needed for that function call

■ Children: The m_type data member contains pointers to anyCParseNode objects that are the children of this object.

■ Value: The m_string_val or the m_number_val data members definea value that is a string or a number (except for TupleType objects,which have no value).

CObject

CParseNode


CParseNode

The highest level CParseNode object in a tree essentially holds all the infor-mation necessary to process an extension. Figure 18 shows the CParseNodeobject 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)

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

Figure 18CParseNode Object Tree for a Complex Function Call

m_string_val = ‘MOVINGAVG’m_type = FunctionType

m_string_val = ‘ASC’m_type = NameType

m_string_val = ‘Measures.Sales Transactions.Units Sold’m_type = NameType

m_number_val = 3m_type = NumberType

The highest level CParseNode object is a FunctionType. It hasa string value that contains the function call ‘RANK’, whichrequires two arguments.

Both CParseNode objects on this levelrepresent arguments for the RANK()function. One argument is a stringcontaining the function call ‘MOVINGAVG’.The other argument specifies the sortingorder (ASC, for ascending) for RANK.

Both CParseNode objects onthis level represent argumentsfor the MOVINGAVG() function.One argument identifies theMeasure being averaged. Theother argument specifies thenumber of values to be averagedfor that measure.

m_string_val = ‘RANK’m_type = FunctionType


CParseNode Class Members

CParseNode Class Members

Data Members

m_children Defines a pointer to an array of CParseNode objects that are thechildren 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 inthis version of the SDK programming interface

m_string_val Provides a string that is the value for this CParseNode object

m_type Identifies the CParseNode object as an enumerated type


CParseNode::m_children

CParseNode::m_childrenCArray<CParseNode*, CParseNode*> m_children;

Remarks

This data member defines a pointer to an array of CParseNode objects thatare the children of this CParseNode object. Through the use of these pointers,CParseNode objects form a tree holding all the information needed to processor validate the syntax of an extension.

CParseNode::m_number_valdouble m_number_val;

Remarks

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

CParseNode::m_statevoid* m_state;

Remarks

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


CParseNode::m_string_val

CParseNode::m_string_valCString m_string_val;

Remarks

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

CParseNode::m_typeenum { NameType, NumberType, TupleType

FunctionType, UnsetType } m_type;

Remarks

This data member identifies the CParseNode object as an enumerated type.The object’s type determines what value the object has (if any), and it deter-mines whether the object is the parent of other CParseNode objects. Thefollowing types are possible:

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

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

TupleType Must have two children objects but cannot have a string ornumber value

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

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


CPlugIn

CPlugIn

A CPlugIn object describes a Snap-In (that is, an .mcx file) to the MetaCubeengine. For every .mcx file, a CPlugIn object should exist. The SDK ExtensionWizard generates a PlugIn.h file that contains all the code needed for aCPlugIn 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 engineuses this version information to load extension files correctly.

CPlugIn Class Members

Operations

m_dll Defines a handle to the Windows DLL file implementing a Snap-In

m_extensions Provides a pointer to an array of CIExtension objects associatedwith this .mcx file

m_metabase Provides a pointer to the Metabase object

CObject

CPlugIn


CPlugIn::m_dll

CPlugIn::m_dllHINSTANCE m_dll;

Remarks

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

CPlugIn::m_extensionsCArray<class CIExtension*, class CIExtension*> 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. Eachextension is represented by a CIExtension object. The array identified by them_extensions data member lists the CIExtension objects associated with this.mcx file.

CPlugIn::m_metabaseclass Metabase* m_metabase;

Remarks

This data member provides a pointer to the Metabase object.


CQueryCube

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 performits calculations and changes on a QueryCube and the data it holds.

The CQueryCube member functions allow you to obtain information aboutthe QueryCube and its contents. You can retrieve the values of cells andlabeling information associated with each row, column, and page. You canchange the value of a cell. Member functions can be used for retrievingQueryCube 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.

CObject

CQueryCube


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 informationand does not report any measure data

Get_m_iparent; Identifies 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 aspecified cell

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

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

GetColDimIndexes; Points a reference to an array that contains indexes to theQueryCategory objects that return values arranged in acolumn orientation

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

GetColLabels; Points a reference to an array containing the column for thespecified column

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



GetPageDimIndexes; Points a reference to an array that contains indexes to theQueryCategory objects that return values arranged in a pageorientation

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

GetPageLabels; Points a reference to an array containing the labels for thespecified page

GetPageSize; Points references to integers indicating the number of rowsand columns on a specified page in the QueryCube

GetRowDimIndexes; Points a reference to an array that contains indexes to theQueryCategory objects that return values arranged in a roworientation

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 thespecified 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

Operations


CQueryCube::DeleteCell

CQueryCube::DeleteCellvoid DeleteCell( long page_num, long rownum, long colnum );

Parameters

Remarks

Call this member function to delete a cell. A hole is left in the QueryCubewhen a cell is deleted, and the hole can remain unfilled.

CQueryCube::DeleteColumnvoid DeleteColumn( long page_num, long colnum );

Parameters

Remarks

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

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 bedeleted

page_num A long integer specifying the page containing the column to bedeleted

colnum A long integer specifying the column to be deleted


CQueryCube::DeletePage

CQueryCube::DeletePagevoid DeletePage( long page_num );

Parameters

Remarks

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

CQueryCube::DeleteRowvoid DeleteRow( long page_num, long rownum );

Parameters

Remarks

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

page_num A long integer specifying the page to be deleted

page_num A long integer specifying the page containing the row to bedeleted

rownum A long integer specifying the row to be deleted


CQueryCube::Get_m_cellcount

CQueryCube::Get_m_cellcountlong& 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 QueryCubecontains.

CQueryCube::Get_m_dimcountlong& Get_m_dimcount();

Return Value

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

Remarks

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


CQueryCube::Get_m_dimonly

CQueryCube::Get_m_dimonlyBOOL& 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 asinformation about a dimension.

Remarks

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

CQueryCube::Get_m_iparentclass 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 ofthis object.


CQueryCube::Get_m_numpages

CQueryCube::Get_m_numpageslong& 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 QueryCubecontains.


CQueryCube::GetCell

CQueryCube::GetCellvoid GetCell( long page_num, long rownum,

long colnum, SCell*& cell );

Parameters

Remarks

Call this member function to point a reference to an SCell structure thatcontains the value for a specified cell. The sdk.h file defines the SCellstructure. Do not modify the values in a SCell structure referenced by thismember function. Instead, use SetCell() to change those values.

For convenience, the members of an SCell structure are listed and definedbelow.

page_num The number of the page containing the cell whose value will bereferenced

rownum The number of the row containing the cell whose value will bereferenced

colnum The number of the column containing the cell whose value will bereferenced

cell A reference that returns a pointer to an SCell structure, which holdsthe value for the specified cell. If the specified cell does not exist, anull pointer is referenced.


cell_format A CString containing the syntax used for formatting numeric datain different display environments. Typically cell formatting issupplied by MetaCube Warehouse Manager, butQueryItem::SetFormatString() can be used to control the format ofcells for a particular QueryItem.


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


CQueryCube::GetCell

Example



column_orientation = TRUE;...


// Get the cell...




CQueryCube::GetCellItemIndex

CQueryCube::GetCellItemIndexvoid GetCellItemIndex( long page_num, long rownum,

long colnum, long& index );

Parameters

Remarks

Call this member function to point a reference to an index that identifies theQueryItem reported in a cell. Multiple cells can report data for the same setof QueryCategory values—such as Alden (for brand), West (for region), andJanuary (for month)—but only one QueryItem value, such as value for UnitsSold or Gross Revenue, can be reported in that cell. GetCellItemIndex() refer-ences the index to the QueryItem that is associated with a particular cell.

The Process function in the template code generated by the SDK ExtensionWizard calls GetCellItemIndex() to determine if the cell’s value applies to thisfunction, as shown in the following example.

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

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

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

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


CQueryCube::GetCellItemIndex

ExampleCQueryCube* qcube = query->Get_m_qcube();



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

long cell_index;



// Is it me?

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


CQueryCube::GetCellKey

CQueryCube::GetCellKeyvoid GetCellKey( long page_num, long rownum, long colnum,

CKeyArray& key );

Parameters

Remarks

Call this member function to point a reference to a CKeyArray that providesall the dimension keys applicable to this cell. For example, consider a querythat reports units sold by brand (oriented by row), region (oriented bycolumn), and month (oriented by page). A CKeyArray retrieved for a cell inthat QueryCube would contain three dimension keys. A typical set ofdimension keys would be Alden (for brand), West (for region), and January(for month).

GetCellKey() is useful for comparing one cell to another.

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

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

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

key A reference that returns a CKeyArray, which provides thedimension keys applicable to this cell. The sdk.h file defines aCKeyArray as a type of CArray containing CDimKey objects.


CQueryCube::GetColDimIndexes

CQueryCube::GetColDimIndexesvoid GetColDimIndexes( CLongArray& dims );

Parameters

Remarks

Call this member function to point a reference to an array containing indexesto the QueryCategory objects that return values arranged in column orien-tation. A query contains a collection of QueryCategory objects and eachreturns values that can be arranged in a row, column, or page orientation. Forexample, if a QueryCube contains values for a collection of six QueryCat-egory objects, and the second and fourth of those QueryCategory objects usea column orientation, GetColDimIndexes() would reference an array thatconsists of the 0-based integers 1 and 3.

dims A reference that returns a CLongArray, which contains indexes tothe QueryCategory objects arranged in a column orientation. Thesdk.h file defines a CLongArray as a type of CArray containinglongs.


CQueryCube::GetColDims

CQueryCube::GetColDimsvoid GetColDims( CStringArray& dimlabels );

Parameters

Remarks

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

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


CQueryCube::GetColLabels

CQueryCube::GetColLabelsvoid GetColLabels( long page_num, long colnum,

CStringArray& labels );

Parameters

Remarks

Call this member function to point a reference to an array that contains thelabels for a specified column. For example, if a QueryCube contains columnsthat list units sold by both company and brand, a column might have a labelfor 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 manip-ulate cells or to compare one cell to another, use the member functionGetCellKey().

page_num The number of the page containing the column whose labels willbe retrieved

colnum The number of the column whose labels will be retrieved

labels A reference that returns a CStringArray, which contains the labelsfor the specified column


CQueryCube::GetDimCounts

CQueryCube::GetDimCountsvoid GetDimCounts( long& page_dims, long& row_dims,

long& col_dims );

Parameters

Remarks

Call this member function to point references to integers that indicate howmany QueryCategory objects return values in page, row, or column orien-tation. For example, if a query has a collection of three QueryCategoryobjects, such as brand, region, and month, this member function determineshow 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);

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

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

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


CQueryCube::GetPageDimIndexes

CQueryCube::GetPageDimIndexesvoid GetPageDimIndexes( CLongArray& dims );

Parameters

Remarks

Call this member function to point a reference to an array containing indexesto the QueryCategory objects that return values arranged in a page orien-tation. A query contains a collection of QueryCategory objects and eachreturns values that can be arranged in a row, column, or page orientation. Forexample, if a QueryCube contains values for a collection of six QueryCat-egory objects, and the second and fourth of those QueryCategory objects usea page orientation, GetPageDimIndexes() would reference an array thatconsists of the 0-based integers 1 and 3.

dims A reference that returns a CLongArray, which contains indexes tothe QueryCategory objects arranged in a page orientation. Thesdk.h file defines a CLongArray as a type of CArray containinglongs.


CQueryCube::GetPageDims

CQueryCube::GetPageDimsvoid GetPageDims( CStringArray& dimlabels );

Parameters

Remarks

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

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


CQueryCube::GetPageLabels

CQueryCube::GetPageLabelsvoid GetPageLabels( long page_num, CStringArray& labels );

Parameters

Remarks

Call this member function to point a reference to an array that contains thelabels for a specified page. For example, if a QueryCube contains pages thatlist units sold by both company and month, a page might have a label for acompany called Electrotron and a second label for the month January. WhenGetPageLabels() is called for that page, it will reference a CStringArray thatcontains the strings ‘Electrotron’ and ‘January’.

GetPageLabels() is most useful for outputting page information. To manip-ulate cells or to compare one cell to another, use the member functionGetCellKey().

page_num The number of the page whose labels will be retrieved

labels A reference that returns a CStringArray, which contains the labelsfor the specified page.


CQueryCube::GetPageSize

CQueryCube::GetPageSizevoid GetPageSize( long page_num, long& rows, long& columns );

Parameters

Remarks

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

Example

CQueryCube* qcube = query->Get_m_qcube();...



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

long max_dist;



.

.

.}

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

rows A reference that returns a long integer, which indicates thenumber of rows on the page specified with page_num

columns A reference that returns a long integer, which indicates thenumber of columns on the page specified with page_num


CQueryCube::GetRowDimIndexes

CQueryCube::GetRowDimIndexesvoid GetRowDimIndexes( CLongArray& dims );

Parameters

Remarks

Call this member function to point a reference to an array containing indexesto the QueryCategory objects that return values arranged in a row orien-tation. A query contains a collection of QueryCategory objects and eachreturns values that can be arranged in a row, column, or page orientation. Forexample, if a QueryCube contains values for a collection of six QueryCat-egory objects, and the second and fourth of those QueryCategory objects usea row orientation, GetRowDimIndexes() would reference an array thatconsists of the 0-based integers 1 and 3.

dims A reference that returns a CLongArray, which contains indexes tothe QueryCategory objects arranged in a row orientation. Thesdk.h file defines a CLongArray as a type of CArray containinglongs.


CQueryCube::GetRowDims

CQueryCube::GetRowDimsvoid GetRowDims( CStringArray& dimlabels );

Parameters

Remarks

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

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


CQueryCube::GetRowLabels

CQueryCube::GetRowLabelsvoid GetRowLabels( long page_num, long rownum,

CStringArray& labels );

Parameters

Remarks

Call this member function to point a reference to an array that contains thelabels for a specified row. For example, if a QueryCube contains rows that listunits sold by both company and brand, one row might have a label for acompany called Electrotron and a second label for a brand called Alden.When GetRowLabels() is called for that row, it will reference a CStringArraythat contains the strings ‘Electrotron’ and ‘Alden’.

GetRowLabels() is most useful for outputting row information. To manip-ulate cells or to compare one cell to another, use the member functionGetCellKey().

page_num The number of the page containing the row whose labels will beretrieved

rownum The number of the row whose labels will be retrieved

labels A reference that returns a CStringArray, which contains the labelsfor the specified row


CQueryCube::InsertColumn

CQueryCube::InsertColumnvoid InsertColumn( long page_num, long colnum,

CKeyArray& keys );

Parameters

Remarks

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

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 keysfor the column being inserted. The sdk.h file defines a CKeyArrayas a type of CArray containing CDimKey objects.


CQueryCube::InsertPage

CQueryCube::InsertPagevoid InsertPage( long page_num, CKeyArray& keys );

Parameters

Remarks

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

page_num The number of the page to be inserted

keys A reference to a CKeyArray that will provide the dimension keysfor the page being inserted. The sdk.h file defines a CKeyArray asa type of CArray containing CDimKey objects.


CQueryCube::InsertRow

CQueryCube::InsertRowvoid InsertRow( long page_num, long rownum, CKeyArray& keys );

Parameters

Remarks

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

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 keysfor the row being inserted. The sdk.h file defines a CKeyArray asa type of CArray containing CDimKey objects.


CQueryCube::SetCell

CQueryCube::SetCellvoid SetCell( long page_num, long rownum, long colnum,

SCell& cell );

Parameters

Remarks

Call this member function to set the value of a cell in a QueryCube. The valueassigned 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 anddefined below:

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 beset

cell A reference to the SCell structure to be used to assign a value to thespecified cell


cell_format A CString containing the syntax used for formatting numeric datain different display environments. Typically cell formatting issupplied by MetaCube Warehouse Manager, butQueryItem::SetFormatString() can be used to control the format ofcells for a particular QueryItem.


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


CQueryCube::SetCell

Example










CSelect

CSelect

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

CSelect Class Members

Operations

Define Defines the return buffers and format for the data containedin a CSelect object

Fetch Retrieves the data whose output buffers and format weredefined by calling Define()

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

CObject

CSelect


CSelect::Define

CSelect::Definevoid Define( long ndefines, long* types, void** bufs,

long* sizes, long** nulls = NULLP(long*) );

Parameters

Remarks

Call this member function to define the return buffers and format for the datacontained in a CSelect object. After Define() has been called, call Fetch() toretrieve the data.

ndefines The number of columns of data contained in a CSelect object.

types A pointer to a long integer or an array of constants specifying thedata type for an argument. The cdb.h file defines a name andconstant for each of the possible data types. They are:



1234


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

sizes An array of pointers defining the sizes of each buffer used toreceive information. A maximum length must be defined for eachbuffer. 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. Thecdb.h file defines a name and constant for each of the null flags.They are:

Name Constant Description

DB_NULLDB_NNULL

-1-3

SQL_NULL_DATASQL_NTS


CSelect::Fetch

CSelect::Fetchlong 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 andformat were defined by calling Define().

CSelect::RowCountlong 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 farby calling Fetch().


Extension

Extension

The Extension class of objects allows you to incorporate the functionality ofextensions into MetaCube. Each Extension object represents a Snap-In (thatis, an .mcx file) that can contain one or more utilities, such as a harmonicmoving average.

After a .cpp file has been compiled in C++ and the resulting .mcx file has beensnapped into MetaCube, the extension can be registered using Explorer oranother tool to append an entry to MetaCube’s initialization file,metacube.ini. This entry, called EnabledExtensions, identifies the file nameand path of the extension and appears under the [Engine] header. When anapplication calls the MetaCube engine, the engine automatically enables theextensions identified in the initialization file.

Do not confuse a CIExtension object with an Extension object. A CIExtensionobject represents a utility contained within a Snap-In, such as a harmonicmoving average. A Snap-In may contain multiple utilities.

CObject

CCmdTarget

COlapObject

Extension


Extension Class Members


Operations

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

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

GetDescription Retrieves a string containing a description of an extension

GetFileName Retrieves a string containing the file name of the compiledextension code

GetFunctions Retrieves a ValueList object containing the functionsincluded in an extension

GetTypes Retrieves a ValueList object that contains the object class towhich a function applies

OnEnabledChanged Issues a notification that the value of m_enabled haschanged.

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

RefreshList An OLE function called to fill a ValueList

Data Members

m_dll A handle to a Windows DLL (dynamic-link library) fileimplementing an extension

m_enabled A Boolean value indicating whether an extension has beenidentified in the metacube.ini file

m_fileName A string containing the file name of the compiled extensioncode

m_ifunctions A ValueList object that contains the functions included in anextension

m_itypes A ValueList object that contains the object class to which afunction applies



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

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

m_plugin A CPlugin object, which encapsulates the lists of all theextensions in a file

Data Members


Extension::GetArguments

Extension::GetArgumentsLPDISPATCH GetArguments( LPCTSTR Function );

Return Value

The IDispatch pointer associated with the ValueList object containing thedescriptions of arguments for the specified function.

Parameters

Remarks

Call this member function to retrieve descriptions of the arguments neededfor each function included in an extension. Arguments are stored in aValueList object in the order in which they must be specified.

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


Extension::GetArgumentTypes

Extension::GetArgumentTypesLPDISPATCH GetArgumentTypes( LPCTSTR Function );

Return Value

The IDispatch pointer associated with the ValueList object containing thedescriptions of the types of arguments for a specified function.

Parameters

Remarks

Call this member function to retrieve a description of the type of eachargument needed for each function included an extension. Argument typesare stored in a ValueList object in the same order as their correspondingarguments.

Extension::GetDescriptionBSTR GetDescription();

Return Value

An OLE string containing a description of an extension.

Remarks

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

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


Extension::GetFileName

Extension::GetFileNameBSTR GetFileName();

Return Value

An OLE string containing the file name of the compiled extension code.

Remarks

Call this member function to retrieve a string containing the file name of thecompiled extension code.

Extension::GetFunctionsLPDISPATCH GetFunctions();

Return Value

The IDispatch pointer associated with a ValueList object.

Remarks

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


Extension::GetTypes

Extension::GetTypesLPDISPATCH GetTypes();

Return Value

The IDispatch pointer associated with a ValueList object.

Remarks

Call this member function to retrieve a ValueList object that contains descrip-tions of the object classes to which functions apply, typically eitherQueryCategory or QueryItem.

Extension::m_dllHINSTANCE 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 filename extension, are a specific type of DLL file.


Extension::m_enabled

Extension::m_enabledBOOL m_enabled;

Remarks

This data member stores a Boolean value. Nonzero indicates the extensionhas been enabled. Zero indicates the extension has not been enabled.

Extensions are enabled in the metacube.ini file. Under the [Engine] section ofthe file, entries read “EnabledExtensions=” and “DisabledExtensions=”. Toenable one or more extensions, enter the full path to the .mcx file containingthe 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 callOnEnabledChanged().

Extension::m_fileNameCString m_fileName;

Remarks

This data member is a string containing the file name of the compiledextension code.


Extension::m_iarguments

Extension::m_iargumentsValueList m_iarguments;

Remarks

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

Extension::m_iargumenttypesValueList m_iargumenttypes;

Remarks

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

Extension::m_ifunctionsValueList m_ifunctions;

Remarks

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


Extension::m_itypes

Extension::m_itypesValueList m_itypes;

Remarks

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

Extension::m_pluginclass CPlugIn* m_plugin;

Remarks

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

Extension::OnEnabledChangedvoid OnEnabledChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuestored by m_enabled has changed.


Extension::RefreshList

Extension::RefreshListvoid RefreshList( class ValueList* list);

Parameters

Remarks

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

Extension::OnFinalReleasevirtual void OnFinalRelease();

Remarks

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

list A pointer to the ValueList object that is being filled.


Extensions

Extensions

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

Extensions Class Members

Operations

Add Creates a new Extension object, which makes that extensionavailable for all subsequent connections between an appli-cation and the MetaCube engine

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

Remove Removes an Extension object from a collection of Extensionobjects

CObject

CCmdTarget

COlapObject

COleCollection

Extensions


Extensions::Add

Extensions::AddLPDISPATCH Add( LPCTSTR FileName );

Return Value

The IDispatch pointer associated with the Extension object being created.

Parameters

Remarks

Call this member function to create a new Extension object, which adds thenew Extension object to a collection of Extension objects and returns a pointerto the new object. Calling this member function also registers the newextension in MetaCube’s initialization file, which makes the extensionavailable in all subsequent connections between an application and theMetaCube engine.

Extensions::OnFinalReleasevirtual void OnFinalRelease();

Remarks

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

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


Extensions::Remove

Extensions::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

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

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


Filter

Filter

MetaCube filters limit the range of data retrieved by a query or incorporatedinto an aggregate table. The Filter class of objects provides a programminginterface for MetaCube functionality related to MetaCube filters. AllMetaCube functionality related to filters can be represented using the Filterclass of objects or the Filters class of object. “Filters” on page 132, describeshow collections of Filter objects are created and associated with other objects.

CObject

CCmdTarget

COlapObject

CMetaObject

Filter


Filter Class Members

Filter Class Members

Operations

DeleteFilter Deletes the metadata storing a filter’s definition, regardlessof whether a Filter object exists within a collection of Filterobjects

GetFilterElements Retrieves a pointer to the FilterElements object that iscontained within a Filter object

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

Get_m_enabled Prevents MetaCube from applying a filter to a query result

Get_m_group Identifies the name of the dimension or fact table by which afilter is grouped

Get_m_iparent Identifies 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 definition of a filter has beenchanged since it was last saved

GetUpdatable Determines whether the current user has privileges tochange the definition of a filter

OnEnabledChanged Call this member function to issue a notification that thevalue returned by Get_m_enabled() has changed

OnGroupChanged Call this member function to issue a notification that thevalue returned by Get_m_group() has changed

Save Saves the definition of a filter

SaveAs Saves a new Filter object, saves an existing Filter objectunder a new name, or saves an existing Filter object to adifferent Folder object

SetName Changes the name of a filter


Filter::DeleteFilter

Filter::DeleteFiltervoid DeleteFilter();

Remarks

Call this member function to delete the metadata in a relational database thatstores a filter’s definition regardless of whether the Filter object exists in acollection of Filter objects.

Filter::Get_m_enabledBOOL& Get_m_enabled();

Return Value

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

Remarks

Call this member function to prevent MetaCube from applying a filter to aquery result. When you change the value returned by this function, youshould call OnEnabledChanged().


Filter::Get_m_group

Filter::Get_m_groupCString& Get_m_group();

Return Value

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

Remarks

Call this member function to retrieve the name of the group, such as adimension or fact table, with which a filter is associated. When you changethe value returned by this function, you should call OnGroupChanged().

For MetaCube Explorer and MetaCube for Excel, the string returned byGet_m_group() is used to associate filters with dimensions. For a filter basedon an attribute, the string is the name of the Dimension object, such asGeography. For a filter based on a measure, the string is Measures.Fact(‘TableName’), such as Measures.Fact(‘Units Sold’). To ensure compatibility withMetaCube Explorer and MetaCube for Excel, you should use Get_m_group()to implement those conventions, but that technique is not mandatory.

Filter::Get_m_iparentclass 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 acollection of Filter objects.


Filter::GetFilterElements

Filter::GetFilterElementsLPDISPATCH 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 FilterElementobjects in the collection provides criteria for the filter.

Filter::GetFolderLPDISPATCH GetFolder();

Return Value

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

Remarks

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


Filter::GetName

Filter::GetNameBSTR 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::GetOwnerBSTR 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 Filterobject. The default owner is the login ID of the user who created the filter.


Filter::GetSaved

Filter::GetSavedBOOL GetSaved();

Return Value

A Boolean value. Nonzero indicates the filter has not changed since it waslast saved; zero indicates the definition of the filter has changed or has neverbeen saved.

Remarks

Call this member function to determine whether the definition of a filter haschanged.

Filter::GetUpdatableBOOL GetUpdatable();

Return Value

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

Remarks

Call this member function to determine whether the current user has privi-leges to change a filter’s definition.

In this release, the return value is always nonzero; the current user alwayshas privileges to change a filter’s definition.


Filter::OnEnabledChanged

Filter::OnEnabledChangedvoid OnEnabledChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_enabled() has changed.

Filter::OnGroupChangedvoid OnGroupChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_group() has changed.

Filter::Savevoid Save();

Remarks

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


Filter::SaveAs

Filter::SaveAsvoid SaveAs( LPCTSTR Name, LPDISPATCH aFolder );

Parameters

Remarks

Call this member function to save a new Filter object, save an existing Filterobject under a new name, or assign an existing Filter object to a differentFolder object. Before calling this function, Get_m_group() should be called tospecify the dimension or fact table with which a filter is grouped.

Filter::SetNamevoid SetName( LPCTSTR lpszNewValue );

Parameters

Remarks

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

Name Specifies the new name of the filter

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

lpszNewValue Points to the text string providing a new name for the filter


FilterElement

FilterElement

MetaCube filters limit the range of data retrieved by a query or incorporatedinto an aggregate table. Each of the individual criteria defining a filter isspecified using a FilterElement object, which identifies values within ameasure, attribute, or dimension element to include or exclude from reports.

A Filter object contains a collection of FilterElement objects. Together thoseFilterElement objects define the characteristics of the Filter. “FilterElements”on page 128 describes how collections of FilterElement objects are createdand associated with other objects.

CObject

CCmdTarget

COlapObject

CMetaObject

FilterElement


FilterElement Class Members

FilterElement Class Members

Operations

Get_m_iparent Identifies 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 objectincludes or excludes

Get_m_operator Retrieves the operator that a FilterElement object uses

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

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

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

OnOperandChanged Issues a notification that the value returned byGet_m_operand() has changed

OnOperatorChanged Issues a notification that the value returned byGet_m_operator() has changed

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


FilterElement::Get_m_iparent

FilterElement::Get_m_iparentclass Filter*& Get_m_iparent();

Remarks

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

FilterElement::Get_m_operandCString& 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 orexcludes from a report.

Remarks

Call this member function to retrieve a reference to a CString containing thevalues within the attribute, dimension element, or measure that a Filter-Element object includes or excludes from a report. An example of an operandstring is " 'Alden'" or "3". When you change the value returned by thisfunction, you should call OnOperandChanged().

Note that the programmer is responsible for ensuring that the operandbelongs in a syntactically correct SQL statement. An operand string is placeddirectly into the SQL. MetaCube does not check syntax or do any processingof the operand string. One exception to this rule is user-defined or time-dependent parameters, which must be enclosed in double brackets ("<<" and">>"). For more information on user-defined or time-dependent parameters,see “FilterElements::Add” on page 3-129.


FilterElement::Get_m_operator

FilterElement::Get_m_operatorCString& Get_m_operator();

Return Value

A reference to a CString containing the operator that a FilterElement objectuses.

Remarks

Call this member function to retrieve a reference to a CString containing theoperator that a FilterElement object uses. An example of an operator string is“>”. When you change the value returned by this function, you should callOnOperatorChanged().

Note that the operator is placed directly into the SQL. MetaCube does notcheck syntax or do any processing. The programmer is responsible forensuring that the operator belongs in a syntactically correct SQL statement.

FilterElement::GetFilterOnBSTR GetFilterOn();

Return Value

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

Remarks

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


FilterElement::GetFilterType

FilterElement::GetFilterTypelong GetFilterType();

Return Value

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

Remarks

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


Other FilterTypeOther 0

Attribute FilterTypeStandard 1

Dimension Element FilterTypeDimensionElement 2

Measure FilterTypeMeasure 3


FilterElement::GetObject

FilterElement::GetObjectLPDISPATCH GetObject();

Return Value

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

Remarks

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

FilterElement::OnOperandChangedvoid OnOperandChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_operand() has changed.

FilterElement::OnOperatorChangedvoid OnOperatorChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_operator() has changed.


FilterElement::SetFilterOn

FilterElement::SetFilterOnvoid SetFilterOn( LPCTSTR lpszNewValue );

Parameters

Remarks

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

lpszNewValue Specifies a new attribute, dimension element, or measurefrom which values are to be selected


FilterElements

FilterElements

The FilterElements class of objects manages collections of FilterElementobjects. With this class of objects, FilterElement objects can be created and aparent object can be identified for a collection of FilterElement objects. Thevarious FilterElement objects in a collection define the characteristics of aFilter.

FilterElements Class Members

Operations

Add Creates a new FilterElement object

Get_m_iparent Identifies the Filter object that contains a FilterElementsobject

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

CObject

CCmdTarget

COlapObject

COleCollection

FilterElements


FilterElements::Add

FilterElements::AddLPDISPATCH Add( LPCTSTR FilterOn, LPCTSTR Operator,

LPCTSTR Operand );

Return Value

The IDispatch pointer associated with the FilterElement object being created.

Parameterss

FilterOn Points to the text string that is the name of the attribute, dimensionelement, 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, notin, 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 alpha-betic value. “Less than” yields values earlier in the alphabeticsequence; “greater than” yields values later in the alphabeticsequence. The “less than” and “greater than” operators cannotapply to a list of values.

■ The “in” operator allows you to include one or more explicitlyidentified values in a FilterElement object, such as the “East” and“West” regions. When using the “in” operator, enclose operandvalues in parentheses and separate them with commas.

■ The “like” operator allows you to specify a set of letters or digits.


FilterElements::Add

Remarks

Call this member function to create a new FilterElement object, which addsthe FilterElement object to a collection of FilterElement objects.

Refer to the Informix Guide to SQL Syntax for complete discussion of operatorand operand syntax.

Note that MetaCube does not check SQL syntax. The programmer is respon-sible for ensuring that the new filter element is a syntactically correct SQLstatement.

Operand Points to the text string specifying the values within the attribute,dimension element, or measure that the new FilterElement objectincludes or excludes.

Time Dependent Filters

Because MetaCube can recognize the date of the most recent trans-action, you can define dynamic, time-dependent filters that caninclude different values depending on which values in the DataWarehouse are most recent. The duration of the period reported corre-sponds to the type of time attribute or dimension element on whichyou are filtering, such as Day, Week, Month, or Quarter.

To create a dynamic time-dependent filter, use one of the followingparameters:

■ 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 theparameter in double brackets, such as <<Current Period>> or <<Last4 Periods>>.

Note that MetaCube can understand the + and - functions in time-dependent filters. For example, <<Current Period - 3>> yields theperiod three periods ago.

User-Defined Parameters

You can create new parameters that prompt users to enter valuesimmediately prior to the execution of a query. Any value can beassigned to these parameters as long as it is enclosed in doublebrackets, such as <<Choose a Brand>>. The string enclosed by doublebrackets is displayed to the end user.


FilterElements::Get_m_iparent

FilterElements::Get_m_iparentclass Filter*& Get_m_iparent;

Return Value

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

Remarks

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

FilterElements::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

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

index A constant representing the FilterElement object to be removedfrom the collection of FilterElement objects. The index constant canbe an integer (the 0-based index of the object) or a string (the nameof the object).


Filters

Filters

The Filters class of objects manages collections of Filter objects. With this classof objects, Filter objects can be created and retrieved. A Filters object alsoidentifies the parent object to which the filters are applied.

Filters Class Members

Operations

AddDefault Creates a new Filter object using the default filter definitionfor a particular group

AddNewFilter Creates a new Filter object

AddSaved Creates a new Filter object by retrieving a filter definitionsaved to metadata and instantiating it in a new Filter object

Get_m_iparent Identifies the object that contains a collection of Filter objects

GetCountGroup Determines how many Filter objects within the collection areassociated 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

CObject

CCmdTarget

COlapObject

COleCollection

Filters


Filters::AddDefault

Filters::AddDefaultLPDISPATCH AddDefault( LPCTSTR DimensionName );

Return Value

The IDispatch pointer associated with a Filter object being created.

Parameters

Remarks

Call this member function to create a Filter object using the default filterdefinition for a particular group. The new Filter object is added to thecollection of Filter objects.

You can call this member function only when adding a Filter object to acollection of Filter objects that is contained within a Query object.

DimensionName Points to the text string that is the name of the group thatprovides a default filter definition


Filters::AddNewFilter

Filters::AddNewFilterLPDISPATCH AddNewFilter( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new Filter object.

Parameters

Remarks

Call this member function to create a new Filter object. The new Filter objectis added to the collection of Filter objects.

After creating the new Filter object, you can define criteria for the filter byadding FilterElement objects to the collection of FilterElement objects.

Name Points to the text string that is the name of the new Filterobject


Filters::AddSaved

Filters::AddSavedLPDISPATCH AddSaved( LPCTSTR Name, LPCTSTR Owner,

LPDISPATCH aFolder );

Return Value

The IDispatch pointer associated with the Filter object being created.

Parameters

Remarks

Call this member function to instantiate a Filter object that has been saved inmetadata and to add the instantiation to the Filters collection.

Through the SDK programming interface, you access any filter definition inthe DSS system. Insuring that users access only their own saved filters is theresponsibility of the User Interface. MetaCube does not provide security formetadata objects.

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

Owner Points to the text string that is the name of the user whocreated the Filter object from which a filter definition is beingretrieved. When retrieving a public filter, specify the owneras the string returned by Metabase::GetPublicUser().

aFolder Provides the IDispatch pointer associated with the Folderobject that contains the Filter object that is beinginstantiated.


Filters::Get_m_iparent

Filters::Get_m_iparentclass 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 Filterobjects. For the RootFolder object, this member function returns a referenceto the Metabase object.

Filters::GetCountGrouplong GetCountGroup( LPCTSTR Group );

Return Value

A long integer providing the number of Filter objects that are in thiscollection and in the specified group.

Parameters

Remarks

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

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


Filters::GetItemGroup

Filters::GetItemGroupLPDISPATCH GetItemGroup( LPCTSTR Group, long index );

Return Value

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

Parameters

Remarks

Call this member function to identify, by means of a sequentially generatedindex number, a Filter object associated with a group.

Group Points to the text string that is the name of the group withwhich the Filter object is associated

index The 0-based index of the Filter object that is associated withthe particular group and belongs to the collection of Filterobjects


Filters::Remove

Filters::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a Filter object from a collection of Filterobjects.

index A constant representing the Filter object to be removed fromthe collection of Filter objects. The index constant can be aninteger (the 0-based index of the object) or a string (the nameof the object).


Folder

Folder

The Folder class of objects provides a programming interface for MetaCubefunctionality related to MetaCube folders. While the actual definitions ofqueries and filters remain stored in MetaCube’s metadata tables, the SDKprogramming interface offers developers a familiar paradigm for organizingthat information.

MetaCube folders can contain queries and filters, and MetaCube folders canalso be contained by other folders. All of this functionality can be representedusing the Folder class of objects or the Folders class of objects. “Folders” onpage 3-146, describes how collections of Folder objects are created andassociated with other Folder objects.

CObject

CCmdTarget

COlapObject

Folder


Folder Class Members

Folder Class Members

Operations

GetFilterNames Retrieves the names of Filter objects associated with thefolder, an owner, and a group

GetFolders Retrieves the pointer to the collection of Folder objects thatthis 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 afolder and an owner

RenameFilter Substitutes a new name, group, and/or owner for a Filterobject associated with a Folder object

RenameQuery Substitutes a new name and/or owner for any Query objectassociated with a Folder object

SetName Sets a new name for a Folder object


Folder::GetFilterNames

Folder::GetFilterNamesLPDISPATCH GetFilterNames( LPCTSTR Owner, LPCTSTR Group );

Return Value

The IDispatch pointer associated with a ValueList object containing filternames.

Parameters

Remarks

Call this member function to retrieve the pointer to the names of filtersassociated with a folder, owner, and group. The owner is the login ID of theuser who saved the filter. The current user can be retrieved by callingMetabase::Get_m_login(). The public user can be retrieved by callingMetabase::GetPublicUser().

ExampleMetabase* metabase;Folder* folder;LPDispatch listdisp;ValueList* namelist; . . .listdisp = folder->GetFilternames( metabase->GetLogin(), “Time” );namelist* = ( ValueList* )metabase->ObjFromIDispatch( listdisp );

Owner Points to the string that names an owner. The owner is thelogin ID of the user who saved the filter.

Group Points to the string that names a group.


Folder::GetFolders

Folder::GetFoldersLPDISPATCH GetFolders();

Return Value

The IDispatch pointer associated with a Folders object.

Remarks

Call this member function to retrieve a pointer to a Folders object. Thereturned Folders object represents the collection of folders contained withinthe Folder object.

Folder::GetFullPathNameBSTR 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.


Folder::GetName

Folder::GetNameBSTR 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::GetQueryNamesLPDISPATCH GetQueryNames( LPCTSTR Owner );

Return Value

The IDispatch pointer associated with a ValueList object containing thenames of queries.

Parameters

Remarks

Call this member function to retrieve the pointer to the names of queriesassociated with a folder and an owner. The owner is the login ID of the userwho saved the queries. To obtain public queries, specify the public user as thename of the user.

Owner Points to the string that names the owner of a query. Theowner is the login ID of the user who saved the query.


Folder::RenameFilter

Folder::RenameFiltervoid RenameFilter( LPCTSTR OldOwner, LPCTSTR OldGroup,

LPCTSTR OldName, LPCTSTR NewOwner, LPCTSTR NewGroup, LPCTSTR NewName );

Parameters

Remarks

Call this member function to change the name, group, and/or owner of anyFilter object associated with a Folder object.

OldOwner Points to the string identifying the current owner of a filter.The owner is the login ID of the user who saved the filter.

OldGroup Points to the string identifying the current group associatedwith the filter.

OldName Points to the string providing the current name of the filter.

NewOwner Points to the string identifying the new owner of the filter.

NewGroup Points to the string identifying the new group associatedwith the filter.

NewName Points to the string providing the new name of the filter.


Folder::RenameQuery

Folder::RenameQueryvoid RenameQuery( LPCTSTR OldOwner, LPCTSTR OldName,

LPCTSTR NewOwner, LPCTSTR NewName );

Parameters

Remarks

Call this member function to change the name and/or owner of any Queryobject associated with a Folder object.

Folder::SetNamevoid SetName( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to change the name of the folder.

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.

lpszNewValue Points to the text string providing a new name for the folder.


Folders

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 Folderobjects and that collection can belong to another Folder object. In this wayMetaCube objects can represent hierarchical collections of folders.

Although the idea of folders may be familiar to users of most operatingsystems, as a MetaCube object they differ in three respects from other objects:

■ The RootFolder object contains the first collection of Folder objects.The RootFolder object is a Folder object in all respects except that itsparent is null. A single RootFolder object belongs to each instance ofa Metabase object.

■ The only collection of objects belonging to a Folder object is anothercollection of Folder objects. Because each Folder object can, in turn,contain a collection of Folder objects, the number of collections isunlimited.

■ The level of a collection of Folder objects varies, with some collec-tions belonging directly to the RootFolder object and othercollections removed from the RootFolder object by any number ofFolder objects.

CObject

CCmdTarget

COlapObject

COleCollection

Folders


Folders Class Members

Folders Class Members

Operations

Add Adds a new Folder object to a collection and returns theIDispatch pointer to that new object

Get_m_iparent Identifies the Folder object that contains a collection ofFolder objects

Remove Removes a Folder object from a collection of Folder objects


Folders::Add

Folders::AddLPDISPATCH Add( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new Folder object.

Parameters

Remarks

Call this member function to create a new Folder object, which adds theFolder object to a collection of Folder objects and returns the IDispatchpointer to the new Folder object.

Folders::Get_m_iparentclass 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 theFolders collection.

Name Points to the text string that is the name of the new Folderobject.


Folders::Remove

Folders::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a Folder object from a collection ofFolder objects.

index A constant representing the Folder object to be removed. Theindex constant can be an integer (the 0-based index of thefolder) or a string (the name of the folder).


Metabase

Metabase

Each Metabase object is a logical representation of a virtual multi-dimen-sional database. The properties of a Metabase object specify the relationaldatabase on which a multi-dimensional system is based, the multi-dimen-sional interface used for accessing that relational database, and the analyticalfunctions available.

A Metabase object is the master object for every MetaCube object. All otherMetaCube objects exist as children, grandchildren, greatgrandchildren, andso forth of the Metabase object. A Metabase object’s collections encompassthe entire range of MetaCube functionality. The Dimensions and FactTablescollections represent a DSS System’s metadata.

Objects in the FactTables and Dimensions collections lay the foundation forthe Data Warehouse to process multi-dimensional queries. Objects in theFilters, Queries, and QueryBackJobs collections actually define those queries,in the multi-dimensional terms inscribed by objects in the Dimensions andFactTables collections.

CObject

CCmdTarget

COlapObject

CMetaObject

Metabase


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 DSSSystem

DBLogout Disconnects MetaCube from the RDBMS

DeleteMetamodel Deletes a DSS System from metadata in theRDBMS

DeleteQuery Deletes the definition of a query, stored as a Queryobject, from the RDBMS metadata

Disconnect Closes the DSS System and disconnects MetaCubefrom the RDBMS

DoSQL Executes a non-SELECT SQL statement

Get_m_clientType Identifies the development environment in whichthe Metabase object has been created

Get_m_configuration Identifies a set of Metabase member functionsused for connecting to the RDBMS

Get_m_connectDatabase Identifies the vendor and model of an RDBMS,such as Informix Online

Get_m_connected Indicates whether a Metabase object is connectedto an RDBMS

Get_m_connectString Identifies the ODBC data source to whichMetaCube is connected or will connect

Get_m_dataSkip Determines whether an Informix RDBMS can skipa dbspace that is unavailable during the course ofprocessing a transaction

Get_m_db Identifies the CDb object that embodies thecurrently active database connection



Get_m_explain Prompts an Informix RDBMS to record executioninformation in a server-side file

Get_m_extensions Retrieves a list of all the registered extensionsavailable to the Metabase object

Get_m_lastUpdate Retrieves the date on which the DSS System’smetadata was last modified

Get_m_localMetamodelFile Retrieves the name of the file storing a local cacheof metadata

Get_m_login Retrieves the user name passed to the RDBMSduring log in

Get_m_maxTotalFetches Determines the number of rows that MetaCubecan retrieve before aborting a query

Get_m_metacube_path Identifies the directory where the MetaCubeengine is installed

Get_m_name Retrieves the string holding the name of the DSSsystem to be created or the DSS system currentlyopen

Get_m_optimization Determines the extent to which the optimizer of anInformix RDBMS evaluates possible executionstrategies for an SQL query

Get_m_password Retrieves the password submitted to the databaseserver

Get_m_pDQPriority Determines the Parallel Data Query (PDQ)Priority of all queries submitted by MetaCube tothe Informix database

Get_m_schema Retrieves the schema for metadata tables

Get_m_suppressDialogs Determines whether the MetaCube statuswindow appears in other applications

GetCurrentTime_ Determines the current date and time, as recordedon the PC’s clock

Operations



GetDimensions Identifies the Dimensions object, which is acollection of all the Dimension objects in the DSSsystem

GetExtensions Identifies the Extensions object, which is acollection of all available Extension objects

GetFactTables Identifies the FactTables object, which is acollection of all the FactTable objects in the DSSsystem

GetMetamodelNames Identifies a ValueList object that lists all DSSSystem names in metadata

GetParent Identifies the application object, which is requiredby OLE

GetPublicUser Returns the name of the user empowered to savequeries and filters that other users can access

GetQueries Identifies the Queries object, which is a collectionof Query objects

GetQueryBackJobs Identifies the QueryBackJobs object, which is acollection of QueryBackJob objects

GetRootFolder Identifies the RootFolder object, the Folder objectcontaining all other folders as children, grand-children, etc.

GetSchemas Identifies the Schemas object, which is a collectionof Schema objects

GetSystemMessages Identifies the SystemMessages object, which is acollection of SystemMessage objects

GetUniqueID Obtains a unique identification number, which istypically used in a multi-threading environmentto ensure that multiple users do not get issued thesame identification number.

ObjFromDispatch Maps an IDispatch pointer, received fromautomation member functions of a class, into theCCmdTarget derived object that implements theinterfaces of the IDispatch object

Operations



OnClientTypeChanged Issues a notification that the value returned byGet_m_clientType() has changed

OnConfigurationChanged Issues a notification that the value returned byGet_m_configuration() has changed

OnConnectDatabaseChanged Issues a notification that the value returned byGet_m_connectDatabase() has changed

OnConnectStringChanged Issues a notification that the value returned byGet_m_connectString() has changed

OnDataSkipChanged Issues a notification that the value returned byGet_m_dataSkip() has changed

OnExplainChanged Issues a notification that the value returned byGet_m_explain() has changed

OnLocalMetamodelFileChanged Issues a notification that the value returned byGet_m_localMetamodelFile() has changed

OnLoginChanged Issues a notification that the value returned byGet_m_login() has changed

OnMetaSchemaChanged Issues a notification that the value returned byGet_m_schema() has changed

OnNameChanged Issues a notification that the value returned byGet_m_name() has changed

OnOptimizationChanged Issues a notification that the value returned byGet_m_optimization() has changed

OnPasswordChanged Issues a notification that the value returned byGet_m_password() has changed

OnPDQPriorityChanged Issues a notification that the value returned byGet_m_pDQPriority() has changed

OpenQuery Instantiates a Query object saved to the metadata

OpenQueryStorage Returns a pointer to a Query object saved in astructured storage object

Operations



OpenDSSSystem Opens a DSS System, as specified using theGet_m_name() member function

Save Saves changes in a DSS System to RDBMSmetadata

SaveAs Saves a new DSS System to RDBMS metadata

Operations


Metabase::CloseDSSSystem

Metabase::CloseDSSSystemvoid CloseDSSSystem();

Remarks

Call this member function to close the existing DSS System.

Metabase::Connectvoid Connect();

Remarks

Call this member function to log into the RDBMS and open a DSS System.

Metabase::CreateNewvoid CreateNew();

Remarks

Call this member function to create a new DSS System. The member functionGet_m_name() provides the name used for the new DSS System.

Although it is not mandatory, you should call Get_m_name() to define aname for a new DSS System before calling CreateNew().

The user running the extension that includes this member function must bea secure user. In other words, in MetaCube Secure Warehouse, that user mustbe granted authority to access Secure Warehouse and MetaCube WarehouseManager.


Metabase::DBLogin

Metabase::DBLoginvoid DBLogin();

Remarks

Call this member function to log into the RDBMS without opening a DSSSystem.

Metabase::DBLogoutvoid DBLogout();

Remarks

Call this member function to disconnect MetaCube from the RDBMS.


Metabase::DeleteMetaModel

Metabase::DeleteMetaModelvoid DeleteMetaModel( LPCTSTR DSSSystemName );

Parameters

Remarks

Call this member function to delete a DSS System from metadata in theRDBMS. You cannot delete a DSS System to which you are connected.


DSSSystemName Points to the text string that is the name of the DSS System tobe deleted.


Metabase::DeleteQuery

Metabase::DeleteQueryvoid DeleteQuery( LPCTSTR Name, LPCTSTR Author,


Parameters

Remarks

Call this member function to delete the definition of a query, stored as aQuery object, from RDBMS metadata.

Metabase::Disconnectvoid Disconnect();

Remarks

Call this member function to close the DSS System and disconnect MetaCubefrom the RDBMS.

Name Points to the string storing the name of the Query object tobe deleted.

Author Points to the text string that is the author of the query to bedeleted. When a query definition is saved, the default valuefor Author is the name of the database user who logged in.

aFolder Provides the IDispatch pointer associated with the Folderthat contains the Query object to be deleted.


Metabase::DoSQL

Metabase::DoSQLvoid DoSQL( LPCTSTR SQL );

Parameters

Remarks

Call this member function to execute any non-SELECT SQL statement.

SQL Points to the text string that holds a non-SELECT SQLstatement


Metabase::Get_m_clientType

Metabase::Get_m_clientTypelong& 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 whichthe Metabase object has been created. When you change the value returnedby this function, you should call OnClientTypeChanged().

The value returned by this member function determines the format in whichMetaCube returns strings. The metacons.h file defines client types andassigns a constant to each type. The following table duplicates the client typeinformation 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


Metabase::Get_m_configuration

Metabase::Get_m_configurationCString& Get_m_configuration();

Return Value

A reference to a string that identifies of a set of parameters stored inMetaCube.ini.

Remarks

Call this member function to identify a configuration, which is equivalent to aset of Metabase parameters used for connecting to the RDBMS. Rather thancalling each member function individually, you can change the valuereturned by Get_m_configuration(). That string makes a call to theMetacube.ini file, and within that file, multiple configurations can be stored.The following table lists the MetaCube.ini parameters and their corre-sponding member functions:

When you change the value returned by Get_m_configuration(), you shouldcall OnConfigurationChanged().

In Version 4.0 and later releases of MetaCube, the MetaCube analysis enginedoes not use this member function. It is retained, however, for compatibilitywith earlier releases.

MetaCube.ini Parameter Metabase Member Function

ConnectDatabase Get_m_connectDatabase()

ConnectString Get_m_connectString()

Login Get_m_login()

Password Get_m_password()

MetamodelSchema Get_m_schema()

MetamodelFile Get_m_localMetamodelFile()

DSSSystemName Get_m_name()

MaxTotalFetches Get_m_maxTotalFetches()


Metabase::Get_m_connectDatabase

Metabase::Get_m_connectDatabaselong& 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 defaultvalue is the vendor defined in the MetaCube.ini file. When you change thevalue returned by this function, you should call OnConnectDatabase-Changed().

The metacons.h file defines vendors and assigns a constant to each. Thefollowing table duplicates the vendor information listed in metacons.h:

Database Vendor Name in Metacons.h Constant

Microsoft Access DBVendorAccess 2

Informix DBVendorInformix 5


Metabase::Get_m_connected

Metabase::Get_m_connectedBOOL& Get_m_connected();

Return Value

A reference to a Boolean value. Nonzero indicates the Metabase object hasconnected to an RDBMS. Zero indicates the connection has not been made.

Remarks

Call this member function to indicate whether a Metabase object hasconnected to an RDBMS.

Note that setting the return value of this member function does not connectyou to an RDBMS.

Metabase::Get_m_connectStringCString& Get_m_connectString();

Return Value

A reference to a string that identifies the name of an ODBC data source.

Remarks

Call this member function to identify the name of an ODBC data source. Thedefault value is the ConnectString parameter defined in the MetaCube.inifile. When you change the value returned by this function, you should callOnConnectStringChanged().


Metabase::Get_m_dataSkip

Metabase::Get_m_dataSkiplong& Get_m_dataSkip();

Return Value

A reference to a long integer that determines how an Informix RDBMSresponds to unavailable rows when attempting to retrieve data.

Remarks

Call this member function to determine whether an Informix RDBMS canskip a dbspace that is unavailable during the course of processing a trans-action. When you change the value returned by this function, you should callOnDataSkipChanged().

The value returned by this member function specifies how an InformixRDBMS responds to unavailable data. The metacons.h file defines constantsfor the possible types of data skipping functionality. The following tableduplicates the data skip constants listed in metacons.h.:

For more information on data skipping, see the SET DATASKIP entry in theInformix Guide to SQL: Syntax.

Data Skip Functionality Name in Metacons.h Constant

Abort query if any requestedrecord is unavailable

DataSkipOff 0

Skip any unavailable records,returning the values that areavailable

DataSkipOn 1

Accept database default forData Skip option

DataSkipDefault 2


Metabase::Get_m_db

Metabase::Get_m_dbCDb*& Get_m_db();

Return Value

A reference to a CDb object.

Remarks

Call this member function to identify the CDb object that embodies thecurrent actively database connection. Do not set the return value of thisfunction.

Metabase::Get_m_extensionsIExtensionArray& Get_m_extensions();

Return Value

A reference to an array that lists all of the registered extensions available tothe Metabase object.

Remarks

Call this member function to retrieve a list of all the registered extensionsavailable to the Metabase object.


Metabase::Get_m_explain

Metabase::Get_m_explainBOOL& Get_m_explain();

Return Value

A reference to a Boolean value. Nonzero prompts an Informix RDBMS torecord information generated by the database-server optimizer. Zero, thedefault value, indicates the Informix database does not record thisinformation.

Remarks

Set the return value of this member function to prompt an Informix RDBMSto record information in a server-side file named sqexplain.out. This filerecords a copy of a query, a plan of execution that the database-serveroptimizer selects, and an estimate of the amount of work. MetaCube activatesthis database feature when it connects to an Informix RDBMS. For moreinformation, see the SET EXPLAIN entry in the Informix Guide to SQL: Syntax.

When you change the value returned by Get_m_explain() you should callOnExplainChanged().


Metabase::Get_m_lastUpdate

Metabase::Get_m_lastUpdateVARIANT& Get_m_lastUpdate();

Return Value

A reference to a datatype that provides the date on which the DSS System’smetadata was last modified.

Remarks

Call this member function to retrieve the date on which the DSS System’smetadata was last modified. Do not set the return value of this function.

Metabase::Get_m_localMetamodelFileCString& Get_m_localMetamodelFile();

Return Value

A reference to a string that identifies the name of the file storing a local copyof metadata.

Remarks

Call this member function to retrieve the name of the file storing a local copyof metadata. The default value is the value for the MetamodelFile parameterdefined in the MetaCube.ini file.

When you change the value returned by Get_m_localMetamodelFile(), youshould call OnLocalMetamodelFileChanged().


Metabase::Get_m_login

Metabase::Get_m_loginCString& Get_m_login();

Return Value

A reference to a string that identifies the user name passed to the RDBMSduring log in.

Remarks

Call this member function to retrieve the user name passed to the RDBMSduring log in. The default is the value for the Login parameter defined in theMetaCube.ini file. When you change the value returned by Get_m_login(),you should call OnLoginChanged().

Metabase::Get_m_maxTotalFetcheslong& Get_m_maxTotalFetches();

Return Value

A reference to a long integer that determines the maximum number of rowsMetaCube can retrieve before aborting a query.

Remarks

Call this member function to determine the maximum number of rowsMetaCube can retrieve before aborting a query.


Metabase::Get_m_metacube_path

Metabase::Get_m_metacube_pathCString& Get_m_metacube_path();

Return Value

A reference to a string that identifies the directory where MetaCube isinstalled.

Remarks

Call this member function to determine the directory where MetaCube isinstalled. Do not set the string returned by Get_m_metacube_path.

Metabase::Get_m_nameCString& Get_m_name();

Return Value

A reference to a string that identifies the name of a DSS System.

Remarks

Call this member function to retrieve the string holding the name of the DSSSystem to be created or the DSS System currently open.


Metabase::Get_m_optimization

Metabase::Get_m_optimizationBOOL& Get_m_optimization();

Return Value

A reference to a Boolean value. Nonzero, the default value, prompts anInformix RDBMS optimizer to consider every possible execution strategy foran SQL query. Zero prompts the RDBMS to reduce the time spent optimizingSQL queries.

Remarks

Set the return value of this member function to determine the extent to whichthe optimizer of an Informix RDBMS evaluates possible execution strategiesfor an SQL query. The optimizer can evaluate every possible executionstrategy for an SQL query, or it can be instructed to reduce the time devotedto SQL queries, which may preclude the optimizer from deploying the mostefficient execution plan. MetaCube sets the optimization level when itconnects to an Informix RDBMS. For more information on optimization, seethe SET OPTIMIZATION entry in the Informix Guide to SQL: Syntax.

When you change the value returned by Get_m_optimization(), you shouldcall OnOptimizationChanged().


Metabase::Get_m_password

Metabase::Get_m_passwordCString& Get_m_password();

Return Value

A reference to a string that identifies the password submitted to the databaseserver.

Remarks

Call this member function to retrieve the password submitted to the databaseserver. The default value can be read from the MetaCube.ini file, if thePassword parameter has been defined there. When you change the valuereturned by Get_m_password(), you should call OnPasswordChanged().

Note that setting the password using the SDK programming interface doesnot automatically record a value in MetaCube’s initialization file. However,MetaCube will read a default password from the initialization file if oneappears there.


Metabase::Get_m_pDQPriority

Metabase::Get_m_pDQPrioritylong& 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 theInformix database.

Remarks

Set the return value of this member function to designate the Parallel DataQuery (PDQ) Priority of all decision support queries submitted by MetaCubeto the Informix database. When you change the value returned byGet_m_pDQPriority(), you should call OnPDQPriorityChanged().

PDQ Priorities determine the extent to which the Informix database executesqueries 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 PDQPRIOTRITY. Use -1 when connecting to databases that do notsupport 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 systemresources that queries can consume. In multiprocessor systems, highPDQ Priorities enable the database to process queries faster.

PDQ Priorities may be limited by environment variables and files establishedby the database administrator when configuring the Informix RDBMS.

MetaCube attempts to set PDQPRIORITY for all queries when it connects toan Informix RDBMS. For more information on PDQ Priority, see the SETPDQPRIORITY entry in the Informix Guide to SQL: Syntax.


Metabase::Get_m_schema

Metabase::Get_m_schemaCString& Get_m_schema();

Return Value

A reference to a string that identifies the schema for metadata tables.

Remarks

Call this member function to retrieve the schema for metadata tables. Thedefault is the value for the MetamodelSchema parameter defined in theMetaCube.ini file. When you change the value returned by Get_m_schema(),you should call OnMetaSchemaChanged().

Metabase::Get_m_suppressDialogsBOOL& Get_m_suppressDialogs();

Return Value

A reference to a Boolean value. Nonzero prevents the MetaCube statuswindows from appearing in an application. Zero, the default value, allowsMetaCube status windows to appear in an application.

Remarks

Set the return value of this member function to determine whether MetaCubestatus windows appear in other applications.


Metabase::GetCurrentTime_

Metabase::GetCurrentTime_VARIANT GetCurrentTime_();

Return Value

A VARIANT that provides the current date and time, as recorded on the PC’sclock.

Remarks

Call this member function to determine the current date and time, asrecorded on the PC’s clock.

Metabase::GetDimensionsLPDISPATCH GetDimensions();

Return Value

The IDispatch pointer associated with the Dimensions object, which is acollection of all the Dimension objects in the DSS system.

Remarks

Call this member function to identify the Dimensions object, which is acollection of all the Dimension objects in the DSS system. A Dimension objectrepresents a set of hierarchically related categories for grouping transactionaldata.


Metabase::GetExtensions

Metabase::GetExtensionsLPDISPATCH GetExtensions();

Return Value

The IDispatch pointer associated with the Extensions object, which is acollection of all registered Extension objects.

Remarks

Call this member function to identify the Extensions object, which is acollection of all registered Extension objects. Each Extension object corre-sponds to a Snap-In (a .mcx file), which provides one or more functionalextensions to MetaCube’s analytical engine.

Metabase::GetFactTablesLPDISPATCH GetFactTables();

Return Value

The IDispatch pointer associated with the FactTables object, which is acollection of all the FactTable objects in the DSS system.

Remarks

Call this member function to identify the FactTables object, which is acollection of all the FactTable objects in the DSS system. A FactTable objectdescribes the location of the fact table containing transaction-level datastored in the Data Warehouse. A FactTable object also describes the dimen-sions to which the fact table joins, the fact table’s size, the measures itcontains, and other information.


Metabase::GetMetaModelNames

Metabase::GetMetaModelNamesLPDISPATCH GetMetaModelNames();

Return Value

The IDispatch pointer to a ValueList object that identifies all DSS Systemnames recorded in MetaCube’s metadata.

Remarks

Call this member function to identify the ValueList object that lists all DSSSystem names recorded in MetaCube’s metadata.

Metabase::GetParentLPDISPATCH GetParent();

Return Value

The IDispatch pointer associated with the application object.

Remarks

Call this member function to identify the application object, which isrequired by OLE for multi-threading.


Metabase::GetPublicUser

Metabase::GetPublicUserBSTR GetPublicUser();

Return Value

The OLE string identifying the user empowered to save queries and filtersthat other users can access.

Remarks

Call this member function to obtain the name of the user empowered to savequeries and filters that other users can access in MetaCube Explorer andMetaCube for Excel. This string is set to “metapub” for current releases ofExplorer and MetaCube for Excel.

Metabase::GetQueriesLPDISPATCH GetQueries();

Return Value

The IDispatch pointer associated with the Queries object, which is acollection of Query objects.

Remarks

Call this member function to identify the Queries object, a collection of allQuery objects that have been saved with Query::SaveAs(), which saves aQuery object with a name and associates that Query object with a folder.


Metabase::GetQueryBackJobs

Metabase::GetQueryBackJobsLPDISPATCH GetQueryBackJobs();

Return Value

The IDispatch pointer associated with the QueryBackJobs object, which is acollection of QueryBackJob objects.

Remarks

Call this member function to identify the QueryBackJobs object, which is acollection of QueryBackJob objects. A QueryBackJob object is created when aquery is submitted for background processing.

Metabase::GetRootFolderLPDISPATCH GetRootFolder();

Return Value

The IDispatch pointer associated with the RootFolder object.

Remarks

Call this member function to identify the RootFolder object. The RootFolderobject is a special folder that consists of only one object and can be the parentof other objects of a similar type. The RootFolder object represents the highestlevel object within the storage interface for queries and filters saved inMetaCube’s data.


Metabase::GetSchemas

Metabase::GetSchemasLPDISPATCH GetSchemas();

Return Value

The IDispatch pointer associated with the Schemas object, which is acollection of Schema objects.

Remarks

Call this member function to identify the Schemas object, which is acollection of Schema objects identifying all the database schemas or tableowners within the RDBMS. Objects in the Schemas collection represent a datadictionary of physical schemas, tables, and columns in the relationaldatabase. Schema objects do not store any of the corresponding multi-dimen-sional properties of these database structures. As such, the Schemascollection exists purely as a reference for supplying values to the objects inthe FactTables and Dimensions collections, which map the relationshipbetween physical structures and multi-dimensional terms and logic.

Metabase::GetSystemMessagesLPDISPATCH GetSystemMessages();

Return Value

The IDispatch pointer associated with the SystemMessages object.

Remarks

Call this member function to identify the SystemMessages object, which is acollection of SystemMessage objects. A SystemMessage object can be createdto distribute a system message, such as the status of the database or a mainte-nance schedule, to the MetaCube family of applications.


Metabase::GetUniqueID

Metabase::GetUniqueIDlong 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 identification number, which istypically used in a multi-threading environment to ensure that multiple usersdo not get issued the same identification number.

Note that when using MetaCube SDK for Snap-Ins, the template .cpp codegenerated by the Extension Wizard supports multi-threading. No additionalprogramming is necessary.

Metabase::ObjFromIDispatchCCmdTarget* ObjFromIDispatch( LPDISPATCH dispatch );

Return Value

A pointer to the CCmdTarget object associated with dispatch.

Parameters

Remarks

Call this function to map an IDispatch pointer, received from automationmember functions of a class, into the CCmdTarget object that implements theinterfaces of the IDispatch object.

dispatch A pointer to an IDispatch object


Metabase::OnClientTypeChanged

Metabase::OnClientTypeChangedvoid OnClientTypeChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_clientType() has changed.

Metabase::OnConfigurationChangedvoid OnConfigurationChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_configuration() has changed.

Metabase::OnConnectDatabaseChangedvoid OnConnectDatabaseChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_connectDatabase() has changed.


Metabase::OnConnectStringChanged

Metabase::OnConnectStringChangedvoid OnConnectStringChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_connectString() has changed.

Metabase::OnDataSkipChangedvoid OnDataSkipChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_dataSkip() has changed.

Metabase::OnExplainChangedvoid OnExplainChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_explain() has changed.


Metabase::OnLocalMetamodelFileChanged

Metabase::OnLocalMetamodelFileChangedvoid OnLocalMetamodelFileChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_localMetamodelFile() has changed.

Metabase::OnLoginChangedvoid OnLoginChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_login() has changed.

Metabase::OnMetaSchemaChangedvoid OnMetaSchemaChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_schema() has changed.


Metabase::OnNameChanged

Metabase::OnNameChangedvoid OnNameChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_name() has changed.

Metabase::OnOptimizationChangedvoid OnOptimizationChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_optimization() has changed.

Metabase::OnPasswordChangedvoid OnPasswordChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_password() has changed.


Metabase::OnPDQPriorityChanged

Metabase::OnPDQPriorityChangedvoid OnPDQPriorityChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_pDQPriority() has changed.

Metabase::OpenQueryLPDISPATCH OpenQuery( LPCTSTR Name, LPCTSTR Author,


Return Value

The IDispatch pointer associated with a Query object.

Parameters

Remarks

Call this member function to instantiate a query definition stored in themetadata.

Name Specifies the name of a Query object for which a querydefinition is being retrieved.

Author Specifies the user who created the Query object for which aquery definition is being retrieved.

aFolder The IDispatch pointer associated with the Folder object thatcontains the Query object for which a query definition isbeing retrieved.


Metabase::OpenQueryStorage

Metabase::OpenQueryStorageLPDISPATCH OpenQueryStorage( LPUNKNOWN Storage );

Return Value

The IDispatch pointer to a Query object.

Parameters

Remarks

Call this member function to return a pointer to a Query object saved in astructured storage object.

Metabase::OpenDSSSystemvoid OpenDSSSystem();

Remarks

Call this member function to open a DSS System, as specified using theGet_m_name() member function. Calling this member function is equivalentto calling OpenDSSSystem2() with its Boolean value set to True.

Storage Points to the structured storage object in which a Queryobject is saved


Metabase::Save

Metabase::Savevoid Save();

Remarks

Call this member function to save changes in a DSS System to the RDBMSmetadata.


Metabase::SaveAsvoid SaveAs( LPCTSTR Name );

Parameters

Remarks

Call this member function to save the current DSS System to the RDBMSmetadata under a new name.


Name Points to a string containing the name of the new DSSSystem


MetaCube

MetaCube

A MetaCube object can be thought of as a virtual cube of data returned whena query is performed. The MetaCube class of objects provide different waysof organizing, summarizing, and pivoting that data. Query data can be repre-sented in a break report, a cross-tabular report, or organized on differentpages. While each new format or calculation manipulates the same set of datareturned to the client, that format or calculation corresponds to a differentMetaCube object within a Query object’s collection of MetaCube objects.

CObject

CCmdTarget

COlapObject

MetaCube


MetaCube Class Members


Operations

ClearSorts Cancels any sort assigned by the SetSortColumn()or SetSortRow() member functions

Copy Copies a MetaCube object and creates a newinstance of that object with the same properties,orientations, sorts, and summaries as the sourceobject

ErrorSpreadClip Returns a tab-delimited string containing the errordata associated with a query result that has beenextrapolated from a sample table

ErrorVBArray Returns a margin of error for each value in anextrapolated query result and assembles thoseerror values into a two-dimensional variant array

FetchCell Returns the value of a specific cell

FetchCellError Returns a number indicating the range of errorassociated with a single value within an extrapo-lated query result

FetchCellType Identifies the type of data in a specified cell

Get_m_column Identifies a particular column in a virtual cube ofdata

Get_m_iparent Identifies the Query object that contains aMetaCube object

Get_m_name Identifies the name of a MetaCube object, asspecified when the MetaCube object was created

Get_m_page Identifies a particular page in a virtual cube ofdata

Get_m_row Identifies a particular row in a virtual cube of data

Get_m_scratch Specifies whether the MetaCube will be savedwith the query’s definition

Get_m_sortColumnBreaks Specifies whether MetaCube performs a numericsort on sub-rows only, leaving rows unsorted



Get_m_sortColumnDirection Specifies a sorting method for the columnidentified by the GetSortColumn() memberfunction

Get_m_sortRowBreaks Specifies whether MetaCube performs a numericsort on sub-columns only, leaving columnsunsorted

Get_m_sortRowDirection Specifies a sorting method for the row identifiedby the GetSortRow() member function

Get_m_suppressDuplicates Specifies whether duplicate values are suppressedin a report that includes rows and sub-rows orcolumns and sub-columns.

GetCell Returns the value of a specific cell

GetCellError Returns a number indicating the range of errorassociated with a single value within an extrapo-lated query result

GetCellType Identifies the type of data in a specified cell

GetColumns Returns the number of columns in the virtual cubeof data represented by a MetaCube object

GetCurrentAttribute Retrieves a pointer to a QueryCategory objectcontaining the attribute or dimension element towhich the currently selected or identified attributeor dimension value belongs

GetFormatStrings Retrieves a pointer to a ValueList object containingformatting commands for each numeric column orrow in the query

GetPageLabels Retrieves a pointer to a ValueList object that storesthe names of attribute values appearing in thepage orientation for a particular page

GetPages Retrieves the number of pages in the virtual cubeof data represented by the MetaCube object

GetRows Retrieves the number of rows in the virtual cube ofdata represented by a MetaCube object

Operations



GetSortColumn Identifies a column of numeric data on which asort will be performed

GetSortRow Identifies a row of numeric data on which a sortwill be performed

GetSummaries Retrieves a pointer to a Summaries object, whichcontains a collection of Summary objects

GetValue Returns the value of a specific cell

OnColumnChanged Issues a notification that the value returned byGet_m_column() has changed

OnNameChanged Issues a notification that the value returned byGet_m_name() has changed

OnPageChanged Issues a notification that the value returned byGet_m_page() has changed

OnRowChanged Issues a notification that the value returned byGet_m_row() has changed

OnSortColumnBreaksChanged Issues a notification that the value returned byGet_m_sortColumnBreaks() has changed

OnSortColumnDirectionChanged Issues a notification that the value returned byGet_m_sortColumnDirection() has changed

OnSortRowBreaksChanged Issues a notification that the value returned byGet_m_sortRowBreaks() has changed

OnSortRowDirectionChanged Issues a notification that the value returned byGet_m_sortRowDirection() has changed

OnSuppressDuplicatesChanged Issues a notification that the value returned byGet_m_suppressDuplicates() has changed

SetSortColumn Specifies a column of numeric data on which a sortwill be performed

Operations



SetSortRow Specifies a row of numeric data on which a sortwill be performed

ToSpreadClip Returns a tab-delimited string that contains thedata stored in the virtual cube represented by aMetaCube object

ToVBArray Translates the virtual cube of data represented bya MetaCube object into a two-dimensional variantarray

Operations


MetaCube::ClearSorts

MetaCube::ClearSortsvoid ClearSorts();

Remarks

Call this member function to cancel any sort assigned by the SetSortColumn()or SetSortRow() member functions. Note that this member function does notcancel sorts assigned by the QueryCategory object’s member functionGet_m_sortDirection().

MetaCube::CopyLPDISPATCH Copy();

Return Value

The IDispatch pointer to the new MetaCube object.

Remarks

Call this member function to copy a MetaCube object and create a newinstance of a MetaCube object with the same properties, sorts, andsummaries as the source object. When the new object is created, the valuereturned by Get_m_scratch() is nonzero, indicating the MetaCube object willnot be saved with the query.


MetaCube::ErrorSpreadClip

MetaCube::ErrorSpreadClipBSTR ErrorSpreadClip( long StartRow, long RowCount );

Return Value

An OLE string containing a tab-delimited string of error data associated witha query result that has been extrapolated from a sample table. If a query doesnot process against a sample table, this member function returns null valuesfor all cells.

Parameters

Remarks

When query results are extrapolated from a sample table, they include arange of error for each numeric value within the result. Call this memberfunction to return a tab-delimited string that contains a page of error dataassociated with a query result that has been extrapolated from a sample table.Before calling this member function, the page should be specified by settingthe return value referenced by Get_m_page().

Attribute values and other non-numeric cells within the report return nullvalues. Null is represented in a tab-delimited string by two tabs with novalue appearing between the tabs.

StartRow Specifies the row within the MetaCube object where theexport of error data should begin. If no value is specified,error data is exported for all rows.

RowCount Specifies the number of rows of error data that should beexported.


MetaCube::ErrorVBArray

MetaCube::ErrorVBArrayVARIANT ErrorVBArray();

Return Value

A VARIANT containing an OLE SafeArray. This member function returnsnull 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 ofthe 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 pageof an extrapolated query result. The error values for each value are assembledin 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. Beforecalling this member function, the page should be specified by setting thereturn value referenced by Get_m_page().

For numeric query results that are extrapolated from a sample table, the errorvalue can be added or subtracted to the result, defining a range within whichthe actual value is likely to fall. The confidence with which MetaCube isrequired to certify that the actual result will fall within a certain range deter-mines the size of the range.

Calling this member function implicitly commands the MetaCube engine toexecute a query.


MetaCube::FetchCell

MetaCube::FetchCellVARIANT FetchCell( long Row, long Column, long Page );

Return Value

A variant containing whatever datatype the specified cell contains.

Parameters

Remarks

Call this member function to return as a variant the value of a specific cellwithin the virtual cube of data represented by a MetaCube object. Calling thismember function before executing a query implicitly commands theMetaCube engine to execute the query.

Note that calling this member function involves building the entire virtualcube of data on the client. Previously established limits on the number ofrows a query can retrieve still apply.

Row Specifies the row containing the desired cell.

Column Specifies the column containing the desired cell.

Page Specifies the page containing the desired cell.


MetaCube::FetchCellError

MetaCube::FetchCellErrordouble FetchCellError( long Row, long Column, long Page );

Return Value

A number of the double type indicating the error associated with a singlevalue within an extrapolated query result. This member function returns anull 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, alsoreturn null error values.

Parameters

Remarks

Call this member function to return a number indicating the range of errorassociated with a single value within an extrapolated query result. Fornumeric query results that are extrapolated from a sample table, the error canbe added or subtracted to the statistically predicted value, defining a rangewithin which the actual value is likely to fall. The confidence with whichMetaCube is required to certify that the actual result will fall within thatrange determines the size of the range.






MetaCube::FetchCellType

MetaCube::FetchCellTypelong FetchCellType( long Row, long Column, long Page );

Return Value

A long integer indicating the type of data in a specified cell.

Parameters

Remarks

Call this member function to return a long integer identifying the type of datain a specified cell. The metacons.h file defines constants for the possible typesof cell data. The following table duplicates the cell type constants listed inmetacons.h.:




Cell Contents Name in Metacons.h Constant

Empty CellTypeEmpty 0

QueryCategory name CellTypeCategoryLabel 1

QueryCategory value CellTypeCategoryValue 2

Label for column or row containingcalculated information

CellTypeSummaryLabel 3

Calculated data, such as subtotals orgrand totals

CellTypeSummaryValue 4

Measure name CellTypeQueryItemLabel 5

Numeric measure value CellTypeQueryItemValue 6


MetaCube::Get_m_column

MetaCube::Get_m_columnlong& 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 ina virtual cube of data represented by a MetaCube object.

MetaCube::Get_m_iparentclass 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 aMetaCube object.


MetaCube::Get_m_page

MetaCube::Get_m_pagelong& 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 ina virtual cube of data represented by a MetaCube object.

MetaCube::Get_m_nameCString& 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 aMetaCube object, as specified when the MetaCube object was created.


MetaCube::Get_m_row

MetaCube::Get_m_rowlong& 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 avirtual cube of data represented by a MetaCube object.

MetaCube::Get_m_scratchBOOL& Get_m_scratch();

Return Value

A reference to a Boolean value. Nonzero, the default, indicates that theMetaCube object, including its subtotals and sorts, will not be saved with thequery’s definition. Zero indicates that the MetaCube object is saved when thequery is saved.

Remarks

Set the return value of this member function to specify whether theMetaCube, including its subtotals and sorts, will be saved with the query’sdefinition.


MetaCube::Get_m_sortColumnBreaks

MetaCube::Get_m_sortColumnBreaksBOOL& Get_m_sortColumnBreaks();

Return Value

A reference to a Boolean value. Nonzero indicates that MetaCube performs anumeric sort on rows within each break. Zero, the default value, indicatesthat MetaCube sorts the entire report so that the smallest measure valuesappear first and the largest last, or vice-versa, regardless of the break towhich a row belongs.

Remarks

Set the return value of this member function to specify whether MetaCubesorts rows within a break or sorts rows without regard to breaks. A breakreport lists values for multiple attributes and sorts them according to one ormore of those attributes. For example, a break report might list the Units Soldby Region and break each region’s sales out according to the Brand attribute,as shown in Figure 19.

Figure 19Sorting Rows

Rows sorted by measure within each breakRows sorted by measure


MetaCube::Get_m_sortColumnDirection

MetaCube::Get_m_sortColumnDirectionlong& 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 forthe column identified by GetSortColumn(). An ascending sort arrangesnumbers so the largest appear at the bottom of a report. The metacons.h filedefines possible sorting methods and assigns a constant to each method. Thefollowing 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


MetaCube::Get_m_sortRowBreaks

MetaCube::Get_m_sortRowBreaksBOOL& Get_m_sortRowBreaks();

Return Value

A reference to a Boolean value. Nonzero indicates that MetaCube performs anumeric sort on columns within each break. Zero, the default value, indicatesthat MetaCube sorts the entire report so that the smallest measure valuesappear first and the largest last, or vice-versa, regardless of the break towhich a column belongs.

Remarks

Set the return value of this member function to specify whether MetaCubesorts columns within a break or sorts columns without regard to breaks. Abreak report lists values for multiple attributes and sorts them according toone or more of those attributes. For example, a break report might list theUnits Sold by Region and break those sales out according to the Brandattribute.


MetaCube::Get_m_sortRowDirection

MetaCube::Get_m_sortRowDirectionlong& 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 forthe row identified by GetSortRow(). An ascending sort arranges numbers sothe largest appear in columns to the right of the report and the smallestappear in columns to the left. The metacons.h file defines possible sortingmethods and assigns a constant to each method. The following table dupli-cates the sorting information listed in metacons.h:






MetaCube::Get_m_suppressDuplicates

MetaCube::Get_m_suppressDuplicatesBOOL& Get_m_suppressDuplicates();

Return Value

A reference to a Boolean value. Nonzero indicates that duplicate values aresuppressed in a report that includes rows and sub-rows or columns and sub-columns. Zero, the default value, indicates that row or column values areduplicated for each value within a sub-row or sub-column.

Remarks

Set the return value of this member function to specify whether duplicatevalues are suppressed in a break report that includes rows and sub-rows orcolumns and sub-columns. A break report includes sub-rows or sub-columnswhen a query is performed on multiple attributes, such as Region and Brand.


MetaCube::GetCell

MetaCube::GetCellVARIANT GetCell();

Return Value


Remarks

Call this member function to return as a variant the value of a specific cellwithin the virtual cube of data represented by a MetaCube object. Use theGet_m_row(), Get_m_column(), and Get_m_page() member functions tospecify the cell.

Calling this member function before executing a query implicitly commandsthe MetaCube engine to execute the query.



MetaCube::GetCellError

MetaCube::GetCellErrordouble GetCellError();

Return Value

A double indicating the range of error associated with the value of a cell. Ifsampling was not used when this MetaCube object was generated, thismember function returns zero.

Remarks

Call this member function to return the range of error associated with thevalue of a particular cell when query results have been extrapolated from asample table. The confidence with which MetaCube is required to certify thatthe actual result will fall within a range of error determines the size of therange. Use the Get_m_row(), Get_m_column(), and Get_m_page() memberfunctions to specify the cell for which a range of error is being retrieved.



MetaCube::GetCellType

MetaCube::GetCellTypelong GetCellType();

Return Value

A long integer indicating the type of data in a specified cell.

Remarks

Call this member function to return a long integer identifying the type of datain a specified cell. Use the Get_m_row(), Get_m_column(), andGet_m_page() member functions to specify the cell.

The metacons.h file defines constants for the possible types of cell data. Thefollowing table duplicates the cell type constants listed in metacons.h.:

The value returned by this member function cannot be changed because thetype of cell depends on the definition of the query and the format of thereport.

Cell Contents Name in Metacons.h Constant

Empty CellTypeEmpty 0

QueryCategory name CellTypeCategoryLabel 1

QueryCategory value CellTypeCategoryValue 2

Label for column or row containingcalculated information

CellTypeSummaryLabel 3

Calculated data, such as subtotals orgrand totals

CellTypeSummaryValue 4

Measure name CellTypeQueryItemLabel 5

Numeric measure value CellTypeQueryItemValue 6


MetaCube::GetColumns

MetaCube::GetColumnslong GetColumns();

Return Value

A long integer providing the number of columns in the virtual cube of datarepresented by a MetaCube object.

Remarks

Call this member function to return a long integer providing the number ofcolumns in the virtual cube of data represented by a MetaCube object. Thenumber of columns depends on the number of attributes, measures, anddimension elements included in a query and the range of values representedby each attribute, measure, or dimension element. Thus the value returnedby this member function cannot be changed.


MetaCube::GetCurrentAttribute

MetaCube::GetCurrentAttributeLPDISPATCH 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 objectcontaining the attribute, dimension element, or function call to which thecurrently selected or identified value belongs.


MetaCube::GetFormatStrings

MetaCube::GetFormatStringsLPDISPATCH GetFormatStrings();

Return Value

The IDispatch pointer to a ValueList object containing formatting commandsfor each numeric column or row in the query.

Remarks

Call this member function to retrieve a ValueList object containingformatting commands for each numeric column or row in the query.QueryItem::Get_m_formatString() determines the formatting commands foreach numeric row or column. Query::GetItemOrientation() determineswhether measures are listed by row or by column.

MetaCube::GetPageLabelsLPDISPATCH GetPageLabels();

Return Value

The IDispatch pointer to a ValueList object that stores the names of attributevalues appearing in the page orientation for a particular page.

Remarks

Call this member function to retrieve a pointer to a ValueList object thatstores the names of attribute values appearing in the page orientation for aparticular page. The Get_m_page() member function identifies the page forwhich attribute values are being retrieved. The ValueList object retrieved bythis member function will contain multiple values if more than one Query-Category has been pivoted to a page orientation.


MetaCube::GetPages

MetaCube::GetPageslong 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 numberof pages in the virtual cube of data represented by the MetaCube object.

MetaCube::GetRowslong 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 cubeof data represented by a MetaCube object. The value returned by thismember function cannot be changed because the number of rows in thevirtual cube depends on the definition of the query and the number ofrecords retrieved by the query.


MetaCube::GetSortColumn

MetaCube::GetSortColumnlong GetSortColumn();

Return Value

A long integer indicating the column of numeric data on which a sort will beperformed.

Remarks

Call this member function to identify a column of numeric data on which asort will be performed.

MetaCube::GetSortRowlong GetSortRow();

Return Value

A long integer indicating the row of numeric data on which a sort will beperformed.

Remarks

Call this member function to identify a row of numeric data on which a sortwill be performed.


MetaCube::GetSummaries

MetaCube::GetSummariesLPDISPATCH GetSummaries();

Return Value

The IDispatch pointer to a Summaries object.

Remarks

Call this member function to retrieve a pointer to a Summaries object, whichcontains a collection of Summary objects. Summary objects represent breakreports, in which calculations are performed on attribute values within alarger grouping of attribute values.

MetaCube::GetValueVARIANT GetValue();

Return Value


Remarks

Call this member function to return as a variant the value of a specific cellwithin the virtual cube of data represented by a MetaCube object. Use theGet_m_row(), Get_m_column(), and Get_m_page() member functions tospecify the cell.




MetaCube::OnColumnChanged

MetaCube::OnColumnChangedvoid OnColumnChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_column() has changed.

MetaCube::OnNameChangedvoid OnNameChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_name() has changed.

MetaCube::OnPageChangedvoid OnPageChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_page() has changed.


MetaCube::OnRowChanged

MetaCube::OnRowChangedvoid OnRowChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_row() has changed.

MetaCube::OnSortColumnBreaksChangedvoid OnSortColumnBreaksChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_sortColumnBreaks() has changed.

MetaCube::OnSortColumnDirectionChangedvoid OnSortColumnDirectionChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_sortColumnDirection() has changed.


MetaCube::OnSortRowBreaksChanged

MetaCube::OnSortRowBreaksChangedvoid OnSortRowBreaksChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_sortRowBreaks() has changed.

MetaCube::OnSortRowDirectionChangedvoid OnSortRowDirectionChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_sortRowDirection() has changed.

MetaCube::OnSuppressDuplicatesChangedvoid OnSuppressDuplicatesChanged();

Return Value

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_suppressDuplicates() has changed.


MetaCube::SetSortColumn

MetaCube::SetSortColumnvoid SetSortColumn( long nNewValue );

Parameters

Remarks

Call this member function to specify the column of numeric data on which asort will be performed. Rows are sorted according to the numeric value of themeasure appearing in each row in the specified column. Columns arenumbered 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 bythis member function.

Any value set using this member function overrides any sort applied to aQueryCategory object organized by rows because SetSortColumn() sortsrows based on the values of a measure rather than the value of an attribute.Unlike QueryCategory::Get_m_sortDirection(), which allows you to sortattribute values regardless of their position in the report, SetSortColumn()allows you to apply a new sort to an arbitrary numeric column within anexisting report. Specifying the column on which to base a sort of rows priorto processing a query can be difficult, however, because the order in whichcolumns appear depends on the query result. In cases where MetaCube sortsnumeric data on rows and columns before the query executes, rows aresorted first.

Using this member function to specify a column of attribute values returnsan error.

nNewValue A long integer specifying the column of numeric data onwhich a sort will be performed. The default value is -1,which directs MetaCube to sort reports using the sortingapproach specified with QueryCategory::Get_m_sort-Direction().


MetaCube::SetSortRow

MetaCube::SetSortRowvoid SetSortRow( long nNewValue );

Parameters

Remarks

Call this member function to specify the row of numeric data on which a sortwill be performed. Columns are sorted according to the numeric value of themeasure appearing in each column. Rows are numbered from top to bottombeginning with zero at the first row in the report.

Any value set using this member function overrides any sort applied to aQueryCategory object organized by columns because SetSortRow() sortscolumns based on the values of a measure rather than the value of anattribute. Because a QueryCategory object is sorted before numeric data issorted, changing the sort on a QueryCategory object organized by rowschanges the values that appear in any given row specified by this memberfunction.

This property allows you to apply a new sort to an existing report. Specifyingthe row on which to base a sort of columns prior to processing a query can bedifficult, however, because the order in which rows appear depends on thequery result. In cases where MetaCube sorts numeric data on rows andcolumns before the query executes, rows are sorted first.

Using this member function to specify a row of attribute values returns anerror.

nNewValue A long integer specifying the row of numeric data on whicha sort will be performed. The default value is -1, whichdirects MetaCube to sort reports using the sorting approachspecified with QueryCategory::Get_m_sortDirection().


MetaCube::ToSpreadClip

MetaCube::ToSpreadClipBSTR ToSpreadClip( long StartRow, long RowCount );

Return Value

An OLE string containing a tab-delimited string containing the data in thevirtual cube represented by a MetaCube object.

Parameters

Remarks

Call this member function to return a tab-delimited string that contains apage of data stored in the virtual cube represented by a MetaCube object.Before calling this member function, the page should be specified by settingthe return value referenced by Get_m_page().


StartRow Specifies the row within the MetaCube object where theexport of data should begin. If no value is specified, data isexported for all rows.

RowCount Specifies the number of rows of data that should beexported.


MetaCube::ToVBArray

MetaCube::ToVBArrayVARIANT ToVBArray();

Return Value

A VARIANT containing an OLE SafeArray.

Remarks

Call this member function to translate a page in the virtual cube of data repre-sented by a MetaCube object into a two-dimensional variant array that canbe stored by a Visual Basic 4.0, Visual Basic for Applications, or C++/MFCvariant or array variable. Before calling this member function, the pageshould be specified by setting the return value referenced by Get_m_page().



MetaCubes

MetaCubes

The MetaCubes class of objects manages collections of MetaCube objects. TheMetaCubes member functions allow you to create and delete MetaCubeobjects and to identify the Query object containing a collection of MetaCubeobjects.

MetaCubes Class Members

Operations

Add Instantiates a new MetaCube object, adds it to the collectionof MetaCube objects, and returns the new object

Get_m_iparent Identifies the Query object that contains a collection ofMetaCube objects

Remove Removes a MetaCube object from a collection of MetaCubeobjects

CObject

CCmdTarget

COlapObject

COleCollection

MetaCubes


MetaCubes::Add

MetaCubes::AddLPDISPATCH Add( LPCTSTR Name );

Return Value

The IDispatch pointer associated with the new MetaCube object.

Parameters

Remarks

Call this member function to instantiate a new MetaCube object, which addsthe new MetaCube object to a collection of MetaCube objects and returns thename of the new MetaCube object.

MetaCubes::Get_m_iparentclass 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 acollection of MetaCube objects.

Name Pointer to the text string that is the name of the newMetaCube object.


MetaCubes::Remove

MetaCubes::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a MetaCube object from a collection ofMetaCube objects.

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


Queries

Queries

The Queries class of objects manages collections of Query objects. A Queryobject contains a collection of attributes, measures, filters, and multi-dimen-sional results. The Queries member functions allow you to add new Queryobjects to the collection and remove Query objects.

Queries Class Members

Operations

Add Adds a new instance of a Query object to this collection andreturns a pointer to that new object

Get_m_iparent Identifies the Metabase object that contains this collection ofQuery objects

Remove Removes a Query object from a collection of Query objects

CObject

CCmdTarget

COlapObject

COleCollection

Queries


Queries::Add

Queries::AddLPDISPATCH Add( LPCTSTR name );

Return Value

The IDispatch pointer for the Query object being created.

Parameters

Remarks

Call this member function to create a Query object, which adds that query tothe collection of Query objects and returns a pointer to the new Query object.

Queries::Get_m_iparentclass 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 thiscollection of Query objects.

name Points to the text string that is the name of the Query object beingcreated


Queries::Remove

Queries::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a Query object from a collection ofQuery objects.

index A constant representing the Query object to be removedfrom the collection of Query objects. The index constant canbe an integer (the 0-based index of the object) or a string (thename of the object).


Query

Query

The Query class of objects represents a collection of QueryCategory,QueryItem, MetaCube and Filter object collections. You can manipulate thosecollections to define the data you want to retrieve from a database. Querydefinitions that include a QueryItem object retrieve transaction-based data.Queries that include only QueryCategory objects retrieve data about therelationships within a dimensional hierarchy. Transaction-based queries(those including a QueryItem) must include at least one QueryCategoryobject by which transactions are grouped, although they can potentiallyinclude an unlimited number of QueryCategory objects.

CObject

CCmdTarget

COlapObject

Query


Query Class Members

Query Class Members

Operations

ClearParameters Erases any values previously applied to the parameters ina query

DeleteQuery Deletes a query definition from the database

Get_m_accuracy Specifies the degree of accuracy with which MetaCubeshould attempt to process a query

Get_m_author Identifies the author of a query

Get_m_autoRefresh Specifies whether a query should re-executeautomatically

Get_m_confidence Specifies the statistical confidence with which MetaCubewill report results extrapolated from sample tables

Get_m_dataSource Specifies the data source for which a query is beingdefined

Get_m_iparent Identifies the Metabase object that is the parent of thisQuery object

Get_m_itemOrientation Determines whether measures returned by a query arebeing 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 thedatabase has generated for this query

Get_m_referenceCount Retrieves the current value of the counter maintained bythe Query object

Get_m_saved Determines whether a query, as currently defined, issaved in the database

GetCost Retrieves a long integer representing the relative perfor-mance cost of executing this query, as returned by theMetaCube Optimizer for any valid transactional querybefore or after execution

GetCurrentData Determines if MetaCube has executed a query and theresults reside in local memory


Query Class Members

GetDrillDataSources Identifies 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 unsavedfilters that have been applied to the query’s definition

GetFolder Retrieves a pointer to the Folder object within which theQuery object has been saved

GetItemOrientation Determines whether measures returned by a query arebeing displayed as rows, columns, or pages

GetLastSaved Retrieves the date and time when the query was lastsaved

GetLastUpdate Retrieves the date and time when the query was lastchanged

GetLive Determines whether a Metabase object defines aconnection to a database so the query can be executed

GetMaximumExceeded Determines whether an executing query returned anumber of rows that exceeded the limit set byMetabase::Get_m_maxTotalFetches()

GetMetaCubes Retrieves a pointer to the collection of MetaCube objectsassociated with this query

GetName Retrieves the name of a Query object

GetParameterObject Identifies the QueryCategory object included in the filterdefinition for a specified parameter

GetParameterOperator Retrieves the operator for an undefined parameter

GetParameters Retrieves the ValueList object containing all undefinedfilter 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 QueryItemobjects

Operations


Query Class Members

GetSQL Retrieves a pointer to the ValueList object containing theSQL generated by the MetaCube engine for any validquery

GetTimeFiltered Determines if a query includes a filter on time

OnAccuracyChanged Issues a notification to MetaCube that the value refer-enced by Get_m_accuracy() has changed

OnConfidenceChanged Issues a notification to MetaCube that the value refer-enced by Get_m_confidence() has changed

OnDataSourceChanged Issues a notification to MetaCube that the value refer-enced by Get_m_dataSource() has changed

Retrieve Commands MetaCube to transmit the SQL generated forthe query directly to the relational database

Save Saves the query definition that is currently held inmemory into the metadata tables in the relationaldatabase

SaveAs Saves the query definition currently stored in memoryinto metadata tables in the relational database and assignsthe 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 filter parameter

SetSQL Replaces an SQL statement that was generated by theMetaCube engine for any valid query

Submit Submits an object for background processing, whichinstantiates a QueryBackJob object

Operations


Query::ClearParameters

Query::ClearParametersvoid ClearParameters();

Remarks

Call this member function to erase any values a procedure previouslyapplied to the parameters in a query. This member function does not bypassor erase parameters values created in MetaCube Agent Administrator, whichalways override parameters assigned by the application.

Query::DeleteQueryvoid DeleteQuery();

Remarks

Call this member function to delete a query definition from the database.


Query::Get_m_accuracy

Query::Get_m_accuracylong& Get_m_accuracy();

Return Value

A reference to a number between 1 and 100 indicating the degree of accuracywith which MetaCube should attempt to process a query.

Remarks

Set the return value of this member function to specify the degree of accuracywith which MetaCube should attempt to process a query. Any value less than100 prompts MetaCube to process the query against a sample table. Therange of accuracy requested for the query directs MetaCube to extrapolate aresult from a larger or smaller sample table.

Query::Get_m_authorCString& 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, thismember function will return the name of the database user provided at login.


Query::Get_m_autoRefresh

Query::Get_m_autoRefreshBOOL& 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 queryshould re-execute automatically.


Query::Get_m_confidence

Query::Get_m_confidencelong& Get_m_confidence();

Return Value

A reference to a number between 1 and 100 indicating the statistical confi-dence with which MetaCube will report results extrapolated from sampletables.

Remarks

Set the return value of this member function to specify the statistical confi-dence with which MetaCube will report results extrapolated from sampletables. As the value of this property increases, the range of error values alsoincreases. For example, MetaCube may be able to predict with 80 percentconfidence that a number falls between 210 and 230. It may predict with only50 percent confidence that the number falls between 215 and 225.

The following member functions of the MetaCube object class return infor-mation about the margin of error for a sampled report:

■ FetchCellError()

■ GetCellError()

■ ErrorVBArray()

■ ErrorSpreadClip()


Query::Get_m_dataSource

Query::Get_m_dataSourceCString& Get_m_dataSource();

Return Value

A reference to a string describing the data source or data sources for which aquery is being defined.

Remarks

Set the return value of this member function to specify the data source (thatis, the fact table) for which a query is being defined. MetaCube does not usethe information specified by this member function when generating SQL fora query. Instead, it uses data specified by the QueryCategory and QueryItemobjects. MetaCube Explorer uses the value returned by this member function.

Query::Get_m_iparentclass 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 ofthis Query object.


Query::Get_m_itemOrientation

Query::Get_m_itemOrientationlong& Get_m_itemOrientation();

Return Value

A reference to a long integer that determines how measures returned by thequery are displayed.

Remarks

Set the value returned by this member function to determine whethermeasures returned by a query are displayed as rows, columns, or pages. Themetacons.h file assigns a constant to each possible orientation. The followingtable duplicates the orientation information listed in metacons.h:

Orientation Name in Metacons.h Constant

Rows OrientationRow 1

Columns OrientationColumn 2

Pages OrientationPage 3


Query::Get_m_name

Query::Get_m_nameCString& 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 isspecified as an argument when a Query object is instantiated. To change thename of a Query object, call SetName().

Query::Get_m_qcubeCQueryCube*& Get_m_qcube();

Return Value

A pointer to the CQueryCube object generated for this query. If a query hasnever 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.


Query::Get_m_referenceCount

Query::Get_m_referenceCountlong& 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 countermaintained by the Query object. Programmers can use this counter forreference purposes. This member function is not the same asCOlapObject::GetRefCount().

Query::Get_m_savedBOOL& Get_m_saved();

Return Value

A reference to a Boolean value. Nonzero indicates the query, as currentlydefined, is saved in the database. Zero indicates the query’s current definitionis not saved.

Remarks

Call this member function to determine whether a query, as currentlydefined, is saved in the database. You should not set the value returned bythis member function.


Query::GetCost

Query::GetCostlong GetCost();

Return Value

A long integer representing the relative performance cost of executing thisquery.

Remarks

Call this member function to retrieve a long integer representing the relativeperformance cost of executing this query, as returned by the MetaCubeOptimizer for any valid transactional query before or after execution. Thisvalue reflects the size of the aggregate table, fact table, or sample table chosenby the MetaCube engine to answer the query. Although this value generallycorresponds to the number of rows in the table, its scale ultimately dependson how the metadata for those tables has been defined. Costs are additive; thecost of queries consisting of multiple SQL statements or SQL statementsaccessing multiple fact or aggregate tables is the sum of the costs for each ofthe tables that must be accessed.


Query::GetCurrentData

Query::GetCurrentDataBOOL GetCurrentData();

Return Value

A Boolean value. Nonzero indicates that MetaCube has executed the queryas currently defined and the results reside in local memory. Zero indicatesMetaCube has not executed the query or the result does not reside in localmemory.

Remarks

Call this member function to determine if MetaCube has executed a queryand the results reside in local memory.


Query::GetDrillDataSources

Query::GetDrillDataSourcesLPDISPATCH GetDrillDataSources();

Return Value

An IDispatch pointer to the DrillDataSources collection, which is a collectionof FactTable objects that can be accessed by a query.

Remarks

Call this member function to identify the FactTable objects that a query canaccess. A query can access measure information from any fact table thatcontains the dimensions included in the query, but the query cannot accessthe appropriate measure information from any fact table that does notcontain the dimensions included in the query. The DrillDataSourcescollection shows the FactTable objects that can potentially be added to aquery. It lists the FactTable objects that contain the dimensions alreadyincluded in the query.

The DrillDataSources collection is available only for reference; applicationscannot instantiate a new item in the collection and the DrillDataSourcescollection has no Add member function.


Query::GetExecutionTime

Query::GetExecutionTimeVARIANT GetExecutionTime();

Return Value

A type that provides the length of time required to execute a query. If thequery is pending execution, null is returned.

Remarks

Call this member function to retrieve the length of time required to execute aquery, as incremented from 12:00:00 A.M.

Query::GetFiltersLPDISPATCH GetFilters();

Return Value

An IDispatch pointer to a collection of saved or unsaved filters that have beenapplied to the query’s definition.

Remarks

Call this member function to retrieve a pointer to a collection of saved orunsaved filters that have been applied to the query’s definition. Any unsavedfilters designed for a particular query exist only within this collection untilthey are saved.


Query::GetFolder

Query::GetFolderLPDISPATCH GetFolder();

Return Value

An IDispatch pointer to the Folder object within which the Query object waslast 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 withinwhich the Query object was last saved.


Query::GetItemOrientation

Query::GetItemOrientationlong GetItemOrientation();

Return Value

A constant that indicates how measures returned by the query are beingdisplayed.

Remarks

Call this member function to determine whether measures returned by aquery are being displayed as rows, columns, or pages. The metacons.h fileassigns a constant to each possible type of orientation. The following tableduplicates the orientation information listed in metacons.h:

To change the orientation of measures returned by a query, callSetItemOrientation().





Query::GetLastUpdate

Query::GetLastUpdateVARIANT 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 waslast changed.

Query::GetLiveBOOL GetLive();

Return Value

A Boolean value. Nonzero indicates a connection to a database has beenestablished to execute the query as it is currently defined. Zero indicates thequery has been defined using a connection to some other database.

Remarks

Call this member function to determine whether a Metabase object defines aconnection to the correct database for the query to be executed. A query canbe defined for another database to which MetaCube is not currentlyconnected but that query cannot be run until MetaCube is connected to theappropriate database.


Query::GetMaximumExceeded

Query::GetMaximumExceededBOOL GetMaximumExceeded();

Return Value

A Boolean value. Nonzero indicates that the query has returned a number ofrows exceeding the limit set by Metabase::Get_m_maxTotalFetches(). Zeroindicates that limit has not been exceeded.

Remarks

Call this member function to determine whether an executing query returneda number of rows that exceeded the limit set by Metabase::Get_m_maxTotal-Fetches().

Query::GetMetaCubesLPDISPATCH 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 MetaCubeobjects associated with this query. A MetaCube object presents a multi-dimensional representation of a query result. This representation is oftencalled a virtual cube of data.


Query::GetName

Query::GetNameBSTR 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 isspecified as an argument when a Query object is instantiated. To change thename of an existing Query object, call SetName().

Query::GetParameterObjectLPDISPATCH GetParameterObject( long index );

Return Value

An IDispatch pointer to a QueryCategory object.

Parameters

Remarks

Call this member function to identify the QueryCategory object included inthe filter definition for a specified parameter. Calling QueryCat-egory::Get_m_category() for that object returns the string containing thename of an Attribute or DimensionElement object or the syntax of anexpression. This information can be used to identify the values that must besupplied to complete the filter.

index The 0-based index specifying the parameter for which aQueryCategory object is necessary.


Query::GetParameterOperator

Query::GetParameterOperatorBSTR GetParameterOperator( long index );

Return Value

An OLE string containing the operator for an undefined parameter.

Parameters

Remarks

Call this member function to retrieve the operator for an undefinedparameter.

Query::GetParametersLPDISPATCH GetParameters();

Return Value

An IDispatch pointer to a ValueList object containing all undefined filterparameters for the query.

Remarks

Call this member function to retrieve the ValueList object containing allundefined filter parameters for the query. These undefined filter parametersare strings containing user prompts, such as <<Please enter a brand>>. TheValueList object does not contain parameters that were previously defined byMetaCube Agent Administrator, the application, or the user.

index The 0-based index specifying a particular undefinedparameter


Query::GetQueryCategories

Query::GetQueryCategoriesLPDISPATCH 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 ofQueryCategory objects, which identify the Attribute objects, Dimension-Element objects, or function calls by which the query groups transactionaldata in the report.

Query::GetQueryItemsLPDISPATCH 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 ofQueryItem objects, which identify the Measure objects or the function callsthat specify the type of numeric data the query retrieves.


Query::GetSQL

Query::GetSQLLPDISPATCH GetSQL();

Return Value

An IDispatch pointer to a ValueList object containing the SQL statementgenerated by the MetaCube engine.

Remarks

Call this member function to retrieve a pointer to the ValueList objectcontaining the SQL statement generated by the MetaCube engine for anyvalid query. Each SQL statement represents a separate string in an array ofvalues. For each different data source or comparison included in the query,MetaCube generates a separate SQL statement.

Query::GetTimeFilteredBOOL GetTimeFiltered();

Return Value

A Boolean value. Nonzero indicates a query includes a filter on time; zeroindicates the query does not include a filter on time.

Remarks

Call this member function to determine if a query includes a filter on time.


Query::OnAccuracyChanged

Query::OnAccuracyChangedvoid OnAccuracyChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_accuracy() has changed.

Query::OnConfidenceChangedvoid OnConfidenceChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_confidence() has changed.

Query::OnDataSourceChangedvoid OnDataSourceChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_dataSource() has changed.


Query::Retrieve

Query::Retrievevoid Retrieve();

Remarks

Call this member function to command MetaCube to transmit the SQLgenerated for the query directly to the relational database. Before it canexecute, the query must consist of at least one QueryCategory object. If thequery contains QueryCategory objects specifying attributes from differentdimensions, the query must also include a QueryItem object.

Several member functions of the MetaCube class of objects implicitly requirequery execution. If one of those member functions are called, it is notnecessary to call Retrieve().

Query::Savevoid Save();

Remarks

Call this member function to save the query definition that is currently storedin memory into the metadata tables in the relational database. The query issaved using the name and author specified by the member functions of theQuery class of objects.

Before calling this member function, SaveAs() must be called at least once toidentify the folder where the query is saved.


Query::SaveAs

Query::SaveAsvoid SaveAs( LPCTSTR Name, LPDISPATCH aFolder );

Parameters

Remarks

Call this member function to save the query definition currently stored inmemory into the metadata tables in the relational database and assign thequery a new name or store it in a different folder.

Query::SaveStoragevoid SaveStorage( LPUNKNOWN Storage );

Parameters

Remarks

Call this member function to save a Query object in a structured storageobject.

Name The new name for the query. The existing name for theQuery object is the name returned by Get_m_name().

aFolder The IDispatch pointer to the folder where you want to savethe query. Two queries with the same name cannot be storedin the same folder.

Storage Points to a structured storage object where this Query objectwill be saved


Query::SetItemOrientation

Query::SetItemOrientationvoid SetItemOrientation( long nNewValue );

Parameters

Remarks

Call this member function to set the orientation of measures returned by aquery. Measures can be displayed as rows or columns. The metacons.h fileassigns a constant to each possible type of orientation. The following tableduplicates the orientation information listed in metacons.h:

Query::SetNamevoid SetName( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to change the name of the Query object, which isinitially specified as an argument when a Query object is instantiated.

nNewValue A constant specifying a type of orientation




lpszNewValue Points to the text string providing a new label for the Queryobject


Query::SetParameter

Query::SetParametervoid SetParameter( long index, LPCTSTR Value);

Parameters

Remarks

Call this member function to assign a value or values to a filter parameter.

Note that when submitting parameterized queries to QueryBack, undefinedparameters must be stored in metadata for future reference by the UNIXprocess clientexec. To identify and define parameters in MetaCube’smetadata, launch MetaCube Agent Administrator. Parameters defined inMetaCube Agent Administrator and registered in MetaCube’s metadata takeprecedence over any parameter assignments made by calling SetParameter().

index The 0-based index of the parameter stored in a ValueListobject. The order of parameters depends on the order inwhich FilterElement objects were instantiated.

Value The values to be substituted for a parameter. These valuesshould be listed in a single text string that conforms to SQLstandards, listing multiple values within parentheses,placing each string value in single quotes, and demarcatingvalues by commas, as in the following example:

(‘Alden’, ‘Delmore’)


Query::SetSQL

Query::SetSQLvoid SetSQL( long index, LPCTSTR Value);

Parameters

Remarks

Call this member function to replace an SQL statement that was generated bythe MetaCube engine for any valid query. For each different data sourceincluded in the query, MetaCube generates a separate SQL statement.

index The 0-based index of an SQL statement in the ValueListobject containing the SQL statements generated by theMetaCube engine for the query

Value A string containing the replacement SQL statement


Query::Submit

Query::SubmitLPDISPATCH Submit(LPCTSTR Name, long Priority,

const VARIANT FAR& TargetStartTime, long RecurType);

Return Value

An IDispatch pointer to a QueryBackJob object instantiated by this memberfunction.

Parameters

Remarks

Call this member function to submit a query for background processing,which instantiates a QueryBackJob object. You cannot submit a query forbackground processing if any of the filters included in the query have notbeen saved.

Name The name assigned to the QueryBack object that this memberfunction will instantiate

Priority A long integer representing the query’s priority. To assign a highpriority, specify a high number. MetaCube Explorer limits priorityvalues to a range of 1 to 5, but the SDK programming interfaceimposes no limits.

TargetStartTime A VARIANT type specifying when the server should process thisquery

RecurType A constant specifying the frequency with which a query should beexecuted. There are several options. The metacons.h file lists theseoptions and assigns a constant to each. The following table dupli-cates the frequency options listed in metacons.h:

Frequency Name in Metacons.h Constant

OnceDailyWeeklyMonthlyAnnually

RecurTypeNoneRecurTypeDailyRecurTypeWeeklyRecurTypeMonthlyRecurTypeAnnually

12345


QueryBackJob

QueryBackJob

Each QueryBackJob object describes the status of a query submitted forbackground processing. When a user submits a query for backgroundprocessing, MetaCube places the query in a job queue. The SQL associatedwith the job is saved in metadata tables. The MetaCube engine assigns anumber to the job and specifies a job type, status, priority, and intended starttime for the job. The queue stores this information.

A simple algorithm determines when jobs run. The administrator sets amaximum number of concurrent jobs, and a server-side scheduling daemonruns jobs until either the maximum number of concurrent jobs is met or nomore 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 jobto be run in the future, the scheduler runs the job at the designated time. Thepriority assigned to jobs determines the order in which concurrent jobs arerun.

To retrieve values for any QueryBack job, you must first call the Refresh-Status() member function. This is necessary because of the nature ofcommunication between the scheduling daemon on the server side andMetaCube on the client side. Both communicate through the Informix tablethat contains the job queue. Periodically, the server-side process automati-cally 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 notautomatically poll. MetaCube obtains information about the queue onlywhen the RefreshStatus() member function is called, which directs MetaCubeto poll the job table.

CObject

CCmdTarget

COlapObject

QueryBackJob


QueryBackJob Class Members


Operations

DeleteJob Deletes a job from the queue.

Get_m_iparent Identifies the Metabase object that is the parent ofa QueryBackJob object

GetErrorCode Retrieves an error code returned by the serverwhile processing a QueryBack job

GetErrorText Retrieves an error message returned by the serverwhile processing a QueryBack job

GetJobID Returns a job ID assigned to a QueryBack job byMetaCube when the job is submitted

GetName Retrieves the name of a QueryBack job, whichcorresponds to the original name of the Queryobject submitted for background processing

GetPriority Retrieves the priority assigned to a QueryBack jobwhen it is submitted

GetRecurType Retrieves the frequency with which the schedulerre-executes a query

GetSize Retrieves the number of rows that a QueryBackJobobject returns to the client

GetStartTime Retrieves the time at which the server beganprocessing a QueryBack job

GetStatus Retrieves the status of a QueryBack job

GetStopTime Retrieves the time at which the server finishedprocessing a QueryBack job

GetSubmitTime Retrieves the time at which at which a usersubmitted a job



GetTargetStart Retrieves the time at which a user requested that aQueryBack job begin processing

RefreshStatus Retrieves and refreshes the values of a Query-BackJob object

Retrieve Retrieves the results of a QueryBack job

Operations


QueryBackJob::DeleteJob

QueryBackJob::DeleteJobvoid DeleteJob();

Remarks

Call this member function to delete a pending or completed job from thequeue. 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 anew incarnation of itself for the following day, month, or year. When appliedto a completed QueryBackJob object, this member function deletes whatevertables store the results of the job.

QueryBackJob::Get_m_iparentclass Metabase*& Get_m_iparent();

Return Value

A pointer to the Metabase object that is the parent of this QueryBackJobobject.

Remarks

Call this member function to identify the Metabase object that is the parent ofa QueryBackJob object.


QueryBackJob::GetErrorCode

QueryBackJob::GetErrorCodelong 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 serverwhile processing a QueryBack job.

QueryBackJob::GetErrorTextBSTR 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 theserver while processing a QueryBack job.


QueryBackJob::GetJobID

QueryBackJob::GetJobIDlong GetJobID();

Return Value

A long integer providing a job identification number.

Remarks

Call this member function to retrieve the unique identification number thatthe scheduling daemon assigns to each QueryBack job when it is submitted.

QueryBackJob::GetNameBSTR 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 namereturned corresponds to the name parameter provided for theQuery::Submit() member function that initiated background processing of aquery.


QueryBackJob::GetPriority

QueryBackJob::GetPrioritylong 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 jobwhen it is submitted.


QueryBackJob::GetRecurType

QueryBackJob::GetRecurTypelong 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 schedulerre-executes a query. Each recurrence of a query automatically creates a newQueryBack job.

There are several options for the frequency with which a query can be re-executed. The metacons.h file lists these options and assigns a constant toeach. The following table duplicates the frequency information listed inmetacons.h:

Frequency Name in Metacons.h Constant

Once RecurTypeNone 1 (default value)

Daily RecurTypeDaily 2

Weekly RecurTypeWeekly 3

Monthly RecurTypeMonthly 4

Annually RecurTypeAnnually 5


QueryBackJob::GetSize

QueryBackJob::GetSizelong GetSize();

Return Value

A long integer providing the number of rows that a QueryBackJob object willreturn 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::GetStartTimeVARIANT GetStartTime();

Return Value

A VARIANT that provides the time at which the server began processing aQueryBack job. Until the job starts, the value returned is null.

Remarks

Call this member function to retrieve the time at which the server beganprocessing a QueryBack job.


QueryBackJob::GetStatus

QueryBackJob::GetStatuslong GetStatus();

Return Value

A long integer indicating whether a QueryBack job is pending, executing, orcomplete.

Remarks

Call this member function to retrieve the status of a QueryBack job. Jobs canbe pending, executing, or complete. All jobs currently in the scheduler’squeue, which includes jobs scheduled to run at a later date, are classified aspending.

The metacons.h file assigns a constant to each classification of a job’s status.The following table duplicates the job status information listed inmetacons.h:

Job Status Name in Metacons.h Constant

Pending QueryBackJobStatusPending 0

Executing QueryBackJobStatusRunning 1

Completed QueryBackJobStatusFinished 2


QueryBackJob::GetStopTime

QueryBackJob::GetStopTimeVARIANT GetStopTime();

Return Value

A VARIANT that provides the time at which the server finished processing aQueryBack job.

Remarks

Call this member function to retrieve the time at which the server finishedprocessing a QueryBack job.

QueryBackJob::GetSubmitTimeVARIANT 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.


QueryBackJob::GetTargetStart

QueryBackJob::GetTargetStartVARIANT GetTargetStart();

Return Value

A VARIANT that provides the time at which a user requested that aQueryBack job begin processing.

Remarks

Call this member function to determine the time at which a user requestedthat a QueryBack job begin processing, as specified in the parameters passedto Query::Submit(). Differences between the value returned by this memberfunction and GetStartTime() result from the length of the job queue, the avail-ability of the scheduler daemon, the time between scheduler polls, and otherfactors.

QueryBackJob::RefreshStatusvoid RefreshStatus();

Remarks

Call this member function to retrieve and refresh the values of a Query-BackJob object. Before calling any other QueryBackJob member function, youmust call RefreshStatus().


QueryBackJob::Retrieve

QueryBackJob::RetrieveLPDISPATCH 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. Thismember function will return a pointer to a Query object. The MetaCubescollection of the Query object will be populated with MetaCube objects forwhich Get_m_scratch() returned FALSE prior to submitting the job forbackground processing.


QueryBackJobs

QueryBackJobs

The QueryBackJobs class of objects manages collections of QueryBackJobobjects. The QueryBackJobs class does not provide a member function thatadds a QueryBackJob object. Query::Submit creates a QueryBackJob object.

A Metabase object contains a collection of QueryBackJob objects. TheMetabase object organizes its collection of QueryBackJob objects by user,showing only those jobs, both pending and complete, that have beensubmitted by a particular user. If a public user, such as “metapub,” creates aQueryBackJob object, other users can access that object.

QueryBackJobs Class Members

Operations

Get_m_iparent Identifies the Metabase object that contains a collection ofQueryBackJob objects

ItemJobID Identifies a QueryBackJob object within a collection ofQueryBackJob objects

RefreshStatus Retrieves and refreshes the values of all the QueryBackJobobjects in a collection

CObject

CCmdTarget

COlapObject

COleCollection

QueryBackJobs


QueryBackJobs::Get_m_iparent

QueryBackJobs::Get_m_iparentclass COlapObject*& Get_m_iparent();

Return Value

A pointer to the Metabase object that contains a collection of QueryBackJobobjects.

Remarks

Use this member function to identify the Metabase object that contains acollection of QueryBackJob objects.

QueryBackJobs::RefreshStatusvoid RefreshStatus();

Remarks

Call this member function to retrieve and refresh the values of all the Query-BackJob objects in a collection.


QueryBackJobs::ItemJobID

QueryBackJobs::ItemJobIDLPDISPATCH ItemJobID( long JobID );

Return Value

The IDispatch pointer to the QueryBackJob object.

Parameters

Remarks

Call this member function to retrieve a QueryBackJob object within acollection of QueryBackJob objects.

JobID The unique identification number that the schedulingdaemon assigns to each QueryBackJob object when the job issubmitted. This number is the index into the QueryBackJobscollection.


QueryCategories

QueryCategories

The QueryCategories class of objects manage collections of QueryCategoryobjects. The QueryCategories member functions allow you to add, remove,and rearrange objects within the collection.

CObject

CCmdTarget

COlapObject

COleCollection

QueryCategories


QueryCategories Class Members

QueryCategories Class Members

Operations

Add Instantiates a new QueryCategory object, adds it to acollection of QueryCategory objects, and returns a pointer tothat new object

Get_m_iparent Identifies the Query object that contains a collection ofQueryCategory objects

MakeFirst Rearranges the order of QueryCategory objects in acollection so a specified object becomes the first item

MakeLast Rearranges the order of QueryCategory objects in acollection so a specified object becomes the last item

MakeNth Rearranges the order of QueryCategory objects in acollection so a specified object is moved to a designatedposition

Remove Removes a QueryCategory object from a collection ofQueryCategory objects

Swap Swaps the position of two QueryCategory objects in acollection


QueryCategories::Add

QueryCategories::AddLPDISPATCH Add( LPCTSTR Category );

Return Value

The IDispatch pointer associated with the QueryCategory object beinginstantiated.

Parameters

Remarks

Call this member function to instantiate a new QueryCategory object, whichadds the new object to a collection of QueryCategory objects and returns apointer to the new QueryCategory object. To avoid ambiguity when speci-fying the name of an object, follow the appropriate scoping rules, asdescribed in the MetaCube Version 3.0 Technical Reference Manual.

Category Pointer to the text string that is the name of an attribute ordimension element or the syntax of an expression to includein a query’s definition.


QueryCategories::Get_m_iparent

QueryCategories::Get_m_iparentclass Query*& Get_m_iparent();

Return Value

A pointer to the Query object that contains a collection of QueryCategoryobjects.

Remarks

Use this member function to identify the Query object that contains acollection of QueryCategory objects.

QueryCategories::MakeFirstvoid MakeFirst( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of QueryCategory objects ina collection so a specified object becomes the first item.

index A VARIANT representing the QueryCategory object to bemoved within the collection of QueryCategory objects. Theindex constant can store an integer (the 0-based index of theobject) or a string (the name of the object).


QueryCategories::MakeLast

QueryCategories::MakeLastvoid MakeLast( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of QueryCategory objects ina collection so a specified object becomes the last item.

QueryCategories::MakeNthvoid MakeNth( const VARIANT FAR& index, long n );

Parameters

Remarks

Call this member function to rearrange a collection of QueryCategory objectsso a specified object can be moved to a designated position in the collection.

index A VARIANT representing the QueryCategory object to bemoved within the collection of QueryCategory objects. Theindex constant can store an integer (the 0-based index of theobject) or a string (the name of the object).

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

n A number specifying the new position for the QueryCat-egory object to be moved


QueryCategories::Remove

QueryCategories::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a QueryCategory object from acollection of QueryCategory objects.

index A constant representing the QueryCategory object to beremoved from the collection of QueryCategory objects. Theindex constant can be an integer (the 0-based index of theobject) or a string (the name of the object).


QueryCategories::Swap

QueryCategories::Swapvoid Swap( const VARIANT FAR& index1,


Parameters

Remarks

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

index1 A constant representing a QueryCategory object whoseposition 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 objectwhose position will be swapped. The index constant can bean integer (the 0-based index of the object) or a string (thename of the object).


QueryCategory

QueryCategory

A QueryCategory object specifies one of the following to include in a query’sdefinition:

■ An Attribute object—describes the physical columns in the relationaldatabase that store string values by which transactional data ischaracterized and grouped

■ A DimensionElement object—identifies a column in the relationaldatabase that defines a particular level in a dimensional hierarchy.This column typically stores a unique code for each value and canjoin to fact or summary tables.

■ A function call—instructs MetaCube to use an extension to performcomplex calculations

CObject

CCmdTarget

COlapObject

QueryCategory


QueryCategory Class Members


Operations

Get_m_category Retrieves a pointer to a string that provides the QueryCat-egory expression, which defines 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 Identifies the parent of this QueryCategory object

Get_m_name Retrieves a pointer to the string containing the label of theQueryCategory object

Get_m_object Retrieves a pointer to the Attribute or DimensionElementobject on which a QueryCategory expression is based

Get_m_orientation Retrieves a reference to a constant that determineswhether values returned by the QueryCategory object aredisplayed in rows, columns, or pages

Get_m_parse Retrieves a reference to a CParseNode object, whichdescribes in detail the operations MetaCube mustperform to process the string returned byGet_m_category().

Get_m_parsed Indicates whether a QueryCategory object has beenparsed

Get_m_sortDirection Retrieves a constant that determines how attribute valueswill be sorted

Get_m_type Classifies the QueryCategory expression as an Attributeobject, 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 expressionis based



OnCategoryChanged Issues a notification that the value referenced byGet_m_category() has changed

OnOrientationChanged Issues a notification that the value referenced byGet_m_orientation() has changed

OnSortDirectionChanged Issues a notification that the value referenced byGet_m_sortDirection() has changed

SetName Changes the label of the QueryCategory object

Operations


QueryCategory::Get_m_category

QueryCategory::Get_m_categoryCString& Get_m_category();

Return Value

A reference to the string containing the name of the object or the syntax of theexpression that defines grouping within a query.

Remarks

Set the value returned by this member function to provide the QueryCat-egory expression, which defines grouping within a query. This memberfunction can return the name of an Attribute or DimensionElement object ora function call. Changing the value returned by this member function altersthe grouping of the query that was originally specified when the QueryCat-egory object was instantiated.

When you change the value returned by this function, you should callOnCategoryChanged().


QueryCategory::Get_m_extension

QueryCategory::Get_m_extensionclass CIExtension*& Get_m_extension();

Return Value

A reference to a CIExtension object. If a QueryCategory object does not needto invoke an extension, MetaCube returns a null value when this memberfunction is called.

Remarks

This member function retrieves a pointer to a CIExtension object when aQueryCategory object needs to invoke an extension. MetaCube determineswhat extension is necessary, if any, by processing the string returned byGet_m_category().

QueryCategory::Get_m_iparentclass 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 thisQueryCategory object.


QueryCategory::Get_m_name

QueryCategory::Get_m_nameCString& Get_m_name();

Return Value

A reference to the string containing the label identifying the QueryCategoryobject. Until a new label has been assigned to the QueryCategory object, thevalue 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 theQueryCategory object. To change a label for a QueryCategory object, use theSetName() member function.

QueryCategory::Get_m_objectclass COlapObject*& Get_m_object();

Return Value

A pointer to the object on which a QueryCategory expression is based. A nullvalue 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 aQueryCategory object represents a bucket or some other expression, thismember function returns a pointer to the Attribute or DimensionElementobject referred to by the syntax of that expression. MetaCube determineswhat Attribute or DimensionElement object is necessary for a QueryCat-egory object by processing the string returned by Get_m_category().


QueryCategory::Get_m_orientation

QueryCategory::Get_m_orientationlong& 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 valuesreturned by the QueryCategory object are displayed in separate rows,columns, or pages. By default, MetaCube displays values in the row orien-tation. The metacons.h file assigns a constant to each possible type oforientation. The following table duplicates the orientation information listedin metacons.h:

Changing the value returned by this member function ultimately requiresthat a new MetaCube object be created, but it does not require the analysisengine to submit another query to the database.

When you change the value returned by this function, you should callOnOrientationChanged().




Pages OrientationPage 3


QueryCategory::Get_m_parse

QueryCategory::Get_m_parseclass CParseNode*& Get_m_parse();

Return Value

A reference to a CParseNode object. If a QueryCategory object has not beenparsed, null is returned.

Remarks

Call this member function to identify the CParseNode object created for aQueryCategory object. The CParseNode object describes in detail whatoperations MetaCube must take to process the string returned byGet_m_category(). The member functions Get_m_extension() andGet_m_object() identify the objects that will perform the operations specifiedby the CParseNode object.

QueryCategory::Get_m_parsedBOOL& 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 byGet_m_category() has been parsed.


QueryCategory::Get_m_sortDirection

QueryCategory::Get_m_sortDirectionlong& 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 valuesreturned by the QueryCategory object are sorted. The metacons.h file definespossible sorting methods and assigns a constant to each method. Thefollowing table duplicates the sorting information listed in metacons.h:

The member functions MetaCube::Get_m_sortColumns() andMetaCube::Get_m_sortRows(), which sort columns or rows on the basis of ameasure’s values, override conflicting sorts specified by this memberfunction.

When you change the value returned by this function, you should callOnSortDirectionChanged().






QueryCategory::Get_m_type

QueryCategory::Get_m_typeenum QueryCatType& Get_m_type();

Return Value

A reference to the QueryCatType enumerated type. The possible Query-CatType values are AttributeType, DimensionElementType, orFunctionType.

Remarks

This member function flags the QueryCategory expression as an Attributeobject, a DimensionElement object, or a function call. MetaCube uses this flagto process the string returned by Get_m_category(). If the flag returned byGet_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 QueryCategoryexpression.

QueryCategory::GetNameBSTR GetName();

Return Value

An OLE string containing the label identifying the QueryCategory object.Until a new label has been assigned to the QueryCategory object, thismember function returns the same string as Get_m_category().

Remarks

Call this member function to retrieve an OLE string containing the label of aQueryCategory object. To change a label for a QueryCategory object, use theSetName() member function.


QueryCategory::GetObject

QueryCategory::GetObjectLPDISPATCH GetObject();

Return Value

A IDispatch pointer to the object on which a QueryCategory expression isbased. A null value is returned for expressions based on multiple Attributeor 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 aQueryCategory object represents a bucket or some other expression, thismember function returns a pointer to the Attribute or DimensionElementobject referred to by the syntax of that expression.

QueryCategory::OnCategoryChangedvoid OnCategoryChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_category() has changed.


QueryCategory::OnOrientationChanged

QueryCategory::OnOrientationChangedvoid OnOrientationChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_orientation() has changed.

QueryCategory::OnSortDirectionChangedvoid OnSortDirectionChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_sortDirection() has changed.


QueryCategory::SetName

QueryCategory::SetNamevoid SetName( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to change the label of the QueryCategory object.Calling this member function leaves the grouping of the query unaltered butchanges 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 thanthe QueryCategory object itself.

lpszNewValue Points to the text string providing a new label for the Query-Category object


QueryItem

QueryItem

A QueryItem object specifies a Measure object or a function call to include ina query’s definition. Measure objects represent numeric data, such as thenumber of units sold or gross revenue. A function call instructs MetaCube touse an extension to perform complex calculations.

CObject

CCmdTarget

COlapObject

QueryItem


QueryItem Class Members


Operations

Get_m_extensions Retrieves a list of all the registered extensions that will becalled by the QueryItem object

Get_m_formatString Retrieves a string that contains the syntax used forformatting numeric data in different displayenvironments

Get_m_iparent Identifies the Query object that is the parent of thisQueryItem object

Get_m_item Retrieves the name of a Measure object or the syntax of afunction call that defines a QueryItem

Get_m_name Retrieves a pointer to the string containing the labeldisplayed in a report as the name of a QueryItem

Get_m_object Retrieves a pointer to the Measure object on which aQueryItem expression is based

Get_m_parse Retrieves a reference to a CParseNode object, whichdescribes in detail the operations MetaCube mustperform to process the string returned by Get_m_item().

Get_m_parsed Indicates whether a QueryItem object has been parsed

Get_m_type Classifies the QueryItem expression as a Measure objector a function call

GetFormatString Retrieves a string that contains the syntax used forformatting numeric data in different displayenvironments

GetItem Retrieves the name of a Measure object or the syntax of acomplex function call that defines a QueryItem

GetName Retrieves an OLE string containing the label of theQueryItem displayed in a report

GetObject Retrieves an IDispatch pointer to the Measure object onwhich a QueryItem expression is based



SetFormatString Defines new syntax used for formatting numeric data indifferent display environments

SetItem Changes the name of a Measure object or the syntax of acomplex function call that defines a QueryItem

SetName Changes the label of the QueryItem displayed in a report

Operations


QueryItem::Get_m_extensions

QueryItem::Get_m_extensionsIExtensionArray& Get_m_extensions();

Return Value

A reference to an array that lists all of the registered extensions that will becalled to process a function.

Remarks

Call this member function to retrieve a list of all the registered extensions thatwill be called if a QueryItem object needs to invoke one or more extensions.MetaCube determines what extensions are necessary by processing the stringreturned by Get_m_item().


QueryItem::Get_m_formatString

QueryItem::Get_m_formatStringCString& 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 usedfor formatting numeric data in different display environments, such as in anExcel Spreadsheet or a reporting control. The syntax returned by this memberfunction defines the formatting for a measure as it will be displayed for aparticular query.

The MetaCube engine stores the formatting information provided byGet_m_formatString(), but MetaCube does not interpret or process thatinformation. Ultimately, an object control or an application will formatmeasure data, interpreting the formatting syntax stored by MetaCube. Thesyntax of the string returned by Get_m_formatString() will vary dependingon the formatting information required by the object control or application.

Use the SetFormatString() member function to change the format string for aQueryItem object. If the QueryItem object’s format string is left empty, theformat string for the measure is used to format the measure’s numeric data.


QueryItem::Get_m_iparent

QueryItem::Get_m_iparentclass 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 ofthis QueryItem object.

QueryItem::Get_m_itemCString& Get_m_item();

Return Value

A reference to the string containing either the name of the measure or theactual syntax of the expression that defines a QueryItem.

Remarks

Call this member function to retrieve the name of a Measure object or thesyntax of a function call that defines a QueryItem.

Use the SetItem() member function to change the value returned by thismember function.


QueryItem::Get_m_name

QueryItem::Get_m_nameCString& Get_m_name();

Return Value

A reference to the string containing the label that is displayed in a report asthe 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 thelabel 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_objectclass 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 onwhich a QueryItem expression is based. When a QueryItem object representsan expression, such as a moving average, this member function returns apointer to the Measure object referred to by the syntax of that expression. Ineither case, MetaCube determines what Measure object should be returnedby processing the string returned by Get_m_item().


QueryItem::Get_m_parse

QueryItem::Get_m_parseclass CParseNode*& Get_m_parse();

Return Value

A reference to a CParseNode object. If a QueryItem object has not beenparsed, null is returned.

Remarks

Call this member function to retrieve a reference to a CParseNode objectcreated for a QueryItem object. The CParseNode object describes in detailwhat operations MetaCube must perform to process the string returned byGet_m_item(). The member functions Get_m_extensions() andGet_m_object() identify the objects that will perform the operations specifiedby the CParseNode object.

QueryItem::Get_m_parsedBOOL& Get_m_parsed();

Return Value

A Boolean value. Nonzero indicates the string returned by Get_m_item() hasbeen parsed. Zero indicates the string has not been parsed.

Remarks

Call this member function to determine if the string returned byGet_m_item() has been parsed.


QueryItem::Get_m_type

QueryItem::Get_m_typeenum 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 QueryItemexpression as a Measure object or a function call. MetaCube uses this flag toprocess the string returned by Get_m_item(). If Get_m_type() flags a Measureobject, Get_m_object() specifies the appropriate object used to process theQueryItem expression. If Get_m_type() flags a function call,Get_m_extensions() specifies the extension or multiple extensions necessaryfor processing the QueryItem expression.


QueryItem::GetFormatString

QueryItem::GetFormatStringBSTR GetFormatString();

Return Value

An OLE string that stores the syntax for a measure’s formatting.

Remarks

Call this member function to retrieve a string that contains the syntax usedfor formatting numeric data in different display environments, such as in anExcel Spreadsheet or a reporting control. The syntax returned by this memberfunction defines the formatting for a measure as it will be displayed for aparticular query.

The MetaCube engine stores the formatting information provided byGet_m_formatString(), but MetaCube does not interpret or process thatinformation. Ultimately, an object control or an application will formatmeasure data, interpreting the formatting syntax stored by MetaCube. Thesyntax of the string returned by Get_m_formatString() will vary dependingon the formatting information required by the object control or application.

Use the SetFormatString() member function to change the format string for aQueryItem object. If the QueryItem object’s format string is left empty, theformat string for the measure is used to format the measure’s numeric data.


QueryItem::GetItem

QueryItem::GetItemBSTR GetItem();

Return Value

An OLE string containing either the name of the measure or the syntax of theexpression that defines a QueryItem.

Remarks

Call this member function to retrieve the name of a Measure object or thesyntax of a complex function call that defines a QueryItem.

Use the SetItem() member function to change the value returned by thismember function.

QueryItem::GetNameBSTR GetName();

Return Value

An OLE string containing the label displayed in a report as the name of aQueryItem. Until a new label has been assigned, the value returned is thesame as the string returned by GetItem().

Remarks

Call this member function to retrieve the string containing the label that isdisplayed in a report as the name of a QueryItem.

To change a label for a QueryItem, use the SetName() member function.


QueryItem::GetObject

QueryItem::GetObjectLPDISPATCH GetObject();

Return Value

An IDispatch pointer to the Measure object on which a QueryItem expressionis based. A null value is returned for expressions based on multiple Measureobjects.

Remarks

This member function retrieves a pointer to the Measure object on which aQueryItem expression is based. When a QueryItem object represents anexpression, such as a moving average, this member function returns a pointerto the Measure object referred to by the syntax of that expression. In eithercase, MetaCube determines what Measure object should be returned byprocessing the string returned by Get_m_item().


QueryItem::SetFormatString

QueryItem::SetFormatStringvoid SetFormatString( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to define new syntax used for formatting numericdata in different display environments, such as in an Excel Spreadsheet or areporting control. This syntax defines the formatting for a measure as it willbe displayed for a particular query. A value for Get_m_formatString() can beset before running a query. Alternatively, the MetaCube::GetFormatStrings()member function returns a ValueList object that provides formatting syntaxfor all measures reported in a query. That ValueList object provides a single,convenient source of all formatting syntax for the application or reportcontrol.

lpszNewValue Points to the text string providing new syntax for ameasure’s formatting. If the QueryItem object’s formatstring is left empty, the format string for the measure is usedto format the measure’s numeric data.


QueryItem::SetItem

QueryItem::SetItemvoid SetItem( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to change the Measure object or the syntax of afunction call that defines a QueryItem. Changing the value of the parameterpassed to this member function alters the numeric data retrieved by thequery, as was originally specified when the QueryItem object wasinstantiated.

QueryItem::SetNamevoid SetName( LPCTSTR lpszNewValue );

Parameters

Remarks

Call this member function to change the label displayed in a report as thename of a QueryItem. Changing this value leaves the numeric data of a queryunaltered.

lpszNewValue Points to the text string providing a new name for a Measureobject or the new syntax for a function call

lpszNewValue Points to the text string providing a new label that will bedisplayed in a report as the name of a QueryItem


QueryItems

QueryItems

The QueryItems class of objects manage collections of QueryItem objects.The QueryItems member functions allow you to add, remove, rearrangeQueryItem objects.

CObject

CCmdTarget

COlapObject

COleCollection

QueryItems


QueryItems Class Members

QueryItems Class Members

Operations

Add Instantiates a new QueryItem object, adds the object to acollection of QueryItem objects, and returns a pointer to thatnew object

Get_m_iparent Identifies the Query object that contains a collection ofQueryItem objects

MakeFirst Rearranges the order of QueryItem objects in a collection soa specified object becomes the first item

MakeLast Rearranges the order of QueryItem objects in a collection soa specified object becomes the last item

MakeNth Rearranges the order of QueryItem objects in a collection soa specified object is moved to a designated position

Remove Removes a QueryItem object from a collection of QueryItemobjects

Swap Swaps the position of two QueryItem objects in a collection


QueryItems::Add

QueryItems::AddLPDISPATCH Add( LPCTSTR Measure );

Return Value

The IDispatch pointer associated with the QueryItem object beinginstantiated.

Parameters

Remarks

Call this member function to instantiate a new QueryItem object, which addsthe new object to a collection of QueryItem objects and returns a pointer tothe new QueryItem object.

QueryItems::Get_m_iparentclass 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 acollection of QueryItem objects.

Category Pointer to the text string that is the name of the measure orthe syntax of a function call to include in a query’s definition.


QueryItems::MakeFirst

QueryItems::MakeFirstvoid MakeFirst( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of QueryItem objects in acollection so the specified object becomes the first item.

QueryItems::MakeLastvoid MakeLast( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of QueryItem objects in acollection so the specified object becomes the last item.

index A constant representing the QueryItem object to be movedwithin the collection of QueryItem objects. The indexconstant can be an integer (the 0-based index of the object) ora string (the name of the object).



QueryItems::MakeNth

QueryItems::MakeNthvoid MakeNth( const VARIANT FAR& index, long n );

Parameters

Remarks

Call this member function to rearrange a collection of QueryItem objects sothe specified object can be moved to a designated position in the collection.

QueryItems::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a QueryItem object from a collection ofQueryItem objects.


n A number specifying the new position for the QueryItemobject to be moved.

index A constant representing the QueryItem object to be removedfrom the collection of QueryItem objects. The indexconstant can be an integer (the 0-based index of the object) ora string (the name of the object).


QueryItems::Swap

QueryItems::Swapvoid Swap( const VARIANT FAR& index1,


Parameters

Remarks

Call this member function to swap the position of two QueryItem objects ina collection of QueryItem objects.

index1 A constant representing the QueryItem object whoseposition will be swapped within the collection of QueryItemobjects. The index constant can be an integer (the 0-basedindex of the object) or a string (the name of the object).

index2 An index representing the other QueryItem object to beswapped. The index constant can be an integer (the 0-basedindex of the object) or a string (the name of the object).


Summaries

Summaries

The Summaries class of objects manage collections of Summary objects. ASummary object performs calculations on groupings within a report. TheSummaries member functions allow you to add new Summary objects to thecollection, remove Summary objects, and rearrange the position of theSummary objects within the collection.

CObject

CCmdTarget

COlapObject

COleCollection

Summaries


Summaries Class Members

Summaries Class Members

Operations

Add Instantiates a new Summary object, adds it to a collection ofSummary objects, and returns a pointer to that new object

Get_m_iparent Identifies the MetaCube object that contains a collection ofSummary objects

MakeFirst Rearranges the order of Summary objects in a collection so aspecified object becomes the first item

MakeLast Rearranges the order of Summary objects in a collection so aspecified object becomes the last item

MakeNth Rearranges the order of Summary objects in a collection so aspecified object is moved to a designated position

Remove Removes a Summary object from a collection of Summaryobjects

Swap Swaps the position of two Summary objects in a collection


Summaries::Add

Summaries::AddLPDISPATCH Add( LPDISPATCH QueryCategory, long SummaryType );

Return Value

The IDispatch pointer associated with the Summary object being created.

Parameters

Remarks

Call this member function to instantiate a new Summary object, which addsthe new object to the collection of Summary objects and returns a pointer tothe new Summary object. The new Summary object will perform a summari-zation on the sub-rows within the report grouping specified by theQueryCategory object. The type of calculation to be performed is determinedby the SummaryType argument. The metacons.h file assigns a constant to eachpossible type of summarization. The following table duplicates the summa-rization information listed in metacons.h:

QueryCategory IDispatch pointer to the QueryCategory object that defines agrouping within a report. All sub-rows within the grouping willbe summed, averaged, or counted. If the value passed in forSummaryType parameter specifies a “Grand” summary, such as aGrandTotal or a GrandAverage, pass in a null value forQueryCategory.

SummaryType A long integer representing the type of calculation to perform

Type of Summarization Name in Metacons.h Constant

Subtotal SummaryTotal 1

Average SummaryAverage 2

Count SummaryCount 3

Minimum SummaryMin 4

Maximum SummaryMax 5


Summaries::Add

Grand Total, All Rows SummaryRowGrandTotal 11

Average, All Rows SummaryRowGrandAverage 12

Count, All Rows SummaryRowGrandCount 13

Minimum Value, Among AllRows

SummaryRowGrandMin 14

Maximum Value, Among AllRows

SummaryRowGrandMax 15

Grand Total, All Columns SummaryColumnGrandTotal 21

Average, All Columns SummaryColumnGrandAverage 22

Count, All Columns SummaryColumnGrandCount 23

Minimum Value, Among AllColumns

SummaryColumnGrandMin 24

Maximum Value, Among AllColumns

SummaryColumnGrandMax 25


Summaries::Get_m_iparent

Summaries::Get_m_iparentclass MetaCube*& Get_m_iparent();

Return Value

A pointer to the MetaCube object that contains a collection of Summaryobjects.

Remarks

Use this member function to identify the MetaCube object that contains acollection of Summary objects.

Summaries::MakeFirstvoid MakeFirst( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of Summary objects in acollection so the specified object becomes the first item.

index A constant representing the Summary object to be movedwithin the collection of Summary objects. The constant mustben an integer (the 0-based index of the object).


Summaries::MakeLast

Summaries::MakeLastvoid MakeLast( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to rearrange the order of Summary objects in acollection so the specified object becomes the last item.

Summaries::MakeNthvoid MakeNth( const VARIANT FAR& index, long n );

Parameters

Remarks

Call this member function to rearrange a collection of Summary objects so thespecified object can be moved to a designated position in the collection.

index A constant representing the Summary object to be movedwithin the collection of Summary objects. The indexconstant can be an integer (the 0-based index of the object) ora string (the name of the object).

index A constant representing the Summary object to be movedwithin the collection of Summary objects. The indexconstant can be an integer (the 0-based index of the object) ora string (the name of the object).

n A number specifying the new position for the Summaryobject to be moved.


Summaries::Remove

Summaries::Removevoid Remove( const VARIANT FAR& index );

Parameters

Remarks

Call this member function to remove a Summary object from a collection ofSummary objects.

Summaries::Swapvoid Swap( const VARIANT FAR& index1,


Parameters

Remarks

Call this member function to swap the position of two Summary objects in acollection of Summary objects.

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

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

index2 An index representing the other Summary object to beswapped. The index constant can be an integer (the 0-basedindex of the object) or a string (the name of the object).


Summary

Summary

A Summary object performs calculations on groupings within a query. Manytypes of calculation can be performed, including sums, averages, counts,minimums, and maximums. Values within a query are grouped by speci-fying a QueryCategory object.

CObject

CCmdTarget

COlapObject

Summary


Summary Class Members

Summary Class Members

Operations

Get_m_iparent Identifies the MetaCube object that is the parent of thisSummary object

Get_m_queryCategory Identifies the QueryCategory object that definesgrouping within a query

Get_m_summaryType Identifies the type of calculation performed on all sub-rows within the grouping specified by the QueryCat-egory object used for this Summary object

GetQueryCategory Retrieves a pointer to the QueryCategory object thatdefines grouping within a query

OnSummaryTypeChanged Issues a notification that the value referenced byGet_m_summaryType() has changed

SetQueryCategory Changes the QueryCategory object that definesgrouping within a query. A calculation is performed onall sub-rows within that grouping.


Summary::Get_m_iparent

Summary::Get_m_iparentclass 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_queryCategoryLPDISPATCH& Get_m_queryCategory();

Return Value

A reference to the IDispatch pointer to the QueryCategory object that definesgrouping 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 objectthat defines grouping within a query. A calculation is performed on all sub-rows within that grouping. To determine what type of calculation isperformed, call Get_m_summaryType(). To define a new QueryCategoryobject for this Summary object, call SetQueryCategory().


Summary::Get_m_summaryType

Summary::Get_m_summaryTypelong& 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 ofcalculation is performed on all sub-rows within the grouping specified by theQueryCategory object. The metacons.h file assigns a constant to each possibletype of summarization. The following table duplicates the summarizationinformation 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 AllRows

SummaryRowGrandMin 14

Maximum Value, Among AllRows

SummaryRowGrandMax 15

Grand Total, All Columns SummaryColumnGrandTotal 21

Average, All Columns SummaryColumnGrandAverage 22


Summary::GetQueryCategory

When you change the value referenced by Get_m_summaryType(), youshould call OnSummaryTypeChanged().

Summary::GetQueryCategoryLPDISPATCH GetQueryCategory();

Return Value

An IDispatch pointer to the QueryCategory object that defines groupingwithin a query report.

Remarks

Call this member function to retrieve a pointer to the QueryCategory objectthat defines grouping within a query. A calculation is performed on all sub-rows within that grouping. To determine what type of calculation isperformed, call Get_m_summaryType(). To define a new QueryCategoryobject for this Summary object, call SetQueryCategory().

Count, All Columns SummaryColumnGrandCount 23

Minimum Value, Among AllColumns

SummaryColumnGrandMin 24

Maximum Value, Among AllColumns

SummaryColumnGrandMax 25


Summary::OnSummaryTypeChanged

Summary::OnSummaryTypeChangedvoid OnSummaryTypeChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereferenced by Get_m_summaryType() has changed.

Summary::SetQueryCategoryvoid SetQueryCategory( LPDISPATCH newValue );

Parameters

Remarks

Call this member function to change the QueryCategory object that definesgrouping within a query. A calculation is performed on all sub-rows withinthe specified grouping. To determine what type of calculation is performed,call Get_m_summaryType().

newValue IDispatch pointer to a new QueryCategory object thatdefines a grouping within a query. A calculation will beperformed on all sub-rows within the grouping.


ValueList

ValueList

Objects of the ValueList class embody lists of values created by some ofMetaCube’s objects. Using the ValueList member functions, you can translatedata in a ValueList object into an array or a tab-delimited string. TheValueList data members allow you to select a subset of the values in theValueList object, choose the maximum number of values to return, andspecify how values are sorted when they are returned.

CObject

CCmdTarget

COlapObject

ValueList


ValueList Class Members

ValueList Class Members

Operations

Get_m_iparent Identifies the object that contains a ValueList object

Get_m_maxRows Specifies a maximum number of values that can bereturned from a ValueList object

Get_m_sort Specifies a method of sorting for the values returnedfrom a ValueList object

Get_m_subset Specifies SQL wildcard syntax, which can be used todefine a subset of the contents of a ValueList object

GetArrayValues Translates the contents of a ValueList object into anOLE SafeArray

GetTabbedValues Translates the contents of a ValueList object into atab-delimited string

OnMaxRowsChanged Issues a notification that the value returned byGet_m_maxRows() has changed

OnSortChanged Issues a notification that the value returned byGet_m_sort() has changed

OnSubsetChanged Issues a notification that the value returned byGet_m_subset() has changed


ValueList::Get_m_iparent

ValueList::Get_m_iparentclass 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 aValueList object.

ValueList::Get_m_maxRowslong& Get_m_maxRows();

Return Value

A reference to a long integer indicating the maximum number of values thatcan be returned from a ValueList object.

Remarks

Set the value returned by this member function to specify a maximumnumber of values that can be returned from a ValueList object. Setting amaximum in this way is especially useful for preventing a tab-delimitedstring derived from a ValueList object from becoming unwieldy. The defaultvalue returned by Get_m_maxRows() is 200.

You can use this data member to limit only a ValueList object that is containedby an Attribute object.

When you change the value returned by this member function, you shouldcall OnMaxRowsChanged().


ValueList::Get_m_sort

ValueList::Get_m_sortlong& Get_m_sort();

Return Value

A reference to a long integer that determines a sorting method for the valuesreturned from a ValueList object.

Remarks

Set the value returned by this member function to specify a sorting methodfor the values returned from a ValueList object. The metacons.h file definespossible sorting methods and assigns a constant to each method. Thefollowing table duplicates the sorting information listed in metacons.h:

You can use this member function to determine the sorting direction of onlya ValueList object that is contained by an Attribute object.

When you change the value returned by this member function, you shouldcall OnSortChanged().



Ascending Order SortDirectionAsc 1



ValueList::Get_m_subset

ValueList::Get_m_subsetCString& 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 wildcardsyntax. Because the wildcard character is appended to the end of any stringreferenced by this member function, you can use this member function toretrieve a subset of the contents of a ValueList object based on the leadingcharacters in the string. A subset established with this member functionapplies to only a ValueList object contained by an Attribute object. To retrieveall values in a ValueList object, set the string referenced by this memberfunction 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 shouldcall OnSubsetChanged().


ValueList::GetTabbedValues

ValueList::GetArrayValuesVARIANT GetArrayValues();

Return Value

An OLE data type containing an OLE SafeArray.

Remarks

Call this member function to translate the contents of a ValueList object intoan OLE SafeArray. For information on how to access an OLE SafeArray, referto the Microsoft Visual C++ product documentation.

ValueList::GetTabbedValuesBSTR GetTabbedValues();

Return Value

An OLE string containing tab-delimited data.

Remarks

Call this member function to translate the contents of a ValueList object intoa tab-delimited string.


ValueList::OnMaxRowsChanged

ValueList::OnMaxRowsChangedvoid OnMaxRowsChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_maxRows() has changed.

ValueList::OnSortChangedvoid OnSortChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_sort() has changed.

ValueList::OnSubsetChangedvoid OnSubsetChanged();

Remarks

Call this member function to issue a notification to MetaCube that the valuereturned by Get_m_subset() has changed.


Index

Index

AAbstract base class 1-5, 1-8, 3-33

for all collection class objects 3-46for all MetaCube objects 3-41

Accuracy of queryspecifying 3-235, 3-237

AddDefault() 3-133Adding

an object to a collection ofExtension objects 3-110Filter objects 3-133, 3-134, 3-135FilterElement objects 3-129Folder objects 3-148MetaCube objects 3-225objects of the same class 3-49Query objects 3-228QueryCategory objects 3-279QueryItem objects 3-313Summary objects 3-319

AddItem() 3-49AddNewFilter() 3-134AddSaved() 3-135Add()

Extensions memberfunction 3-110

FilterElements memberfunction 3-129

Folders member function 3-148MetaCubes member

function 3-225Queries member function 3-228QueryCategories member

function 3-279QueryItems member

function 3-313

Summaries memberfunction 3-319

Applicationidentifying 3-42, 3-43

Argumentsfor an extension

changing argument types 2-8changing descriptions 2-6list of those needed 3-106validating 2-9 to 2-12

Arguments() functionin .cpp file 2-6, 3-29

ArgumentTypeslist of those needed for an

extension 3-106ArgumentTypes() function

in .cpp file 2-8, 3-30Array

of null valuesmacro for making 1-13

types 1-15Assigning

valueto a CDimKey object 3-27to a filter parameter 3-258

Attributenames in MetaCube object

retrieving 3-213object 3-287

Author of a queryidentifying 3-235

Automatic execution of aquery 3-236

BBoolean data type 1-10Buffer sizes 1-14

CCDb class 3-3 to 3-17, 3-95

Commit() 3-5DeleteString() 3-5EndSelect() 3-6ExecuteStmt()

requiring no runtimearguments 3-7

requiring runtimearguments 3-8

GetColumns() 3-10GetDataSources() 3-11GetString() 3-12GetTables() 3-13GetUsers() 3-14list of members 3-4PutString() 3-15Rollback() 3-15SelectStmt() 3-16

CDb objectidentifying 3-166

CDimKeyclass 3-18 to 3-27

CDimKey() 3-20Hash() 3-21list of members 3-19m_group 3-21m_selfsort 3-22m_sortval 3-22m_string 3-23operator<() 3-25operator==() 3-26operator>() 3-24SetFrom() 3-27

objectsassigning values 3-27comparing 3-24, 3-25, 3-26constructing 3-20grouping 3-21sorting 3-22string value of 3-23

CDimKey() 3-20

Cell type constants 3-199Cells

in a CQueryCube objectcounting 3-71deleting 3-69retrieving applicable dimension

keys 3-78retrieving indexes 3-76retrieving value 3-74setting value 3-93

in a MetaCube objectretrieving data types 3-199,

3-210retrieving error values 3-198retrieving values 3-197, 3-208,

3-216cell_error, member of an SCell

structure 3-74, 3-93cell_format, member of an SCell

structure 3-74, 3-93cell_item_index, member of an

SCell structure 3-74, 3-93cell_value, member of an SCell

structure 3-74, 3-93Changes to a database

confirming 3-5undoing 3-15

Changingname of

filter 3-120Query object 3-257QueryCategory object 3-296QueryItem object 3-310

Child object 1-5Children of a CParseNode

object 3-62CIExtension

class 3-28 to 3-32list of members 3-28m_arguments 3-29m_argumenttypes 3-30m_processitem 3-31m_type 3-31m_validate 3-32

object 3-288Class

hierarchyfor C++ API, illustrated 1-6

not available through C++ API,illustrated 1-7

to which an object belongsidentifying 3-45macro 1-12, 1-13

Classesto which extension functions

apply 3-104, 3-107Clearing

parameters applied to aquery 3-234

sorts in a MetaCube 3-194ClearParameters() 3-234ClearSorts() 3-194Client type constants 3-161CloseDSSSystem() 3-156Closing

the DSS System 3-156CMetaObject class 1-8, 3-33 to 3-38

GetDirty() 3-35GetVerified() 3-36GetVerifyResults() 3-37list of members 3-34Verify() 3-38

Code for sample extension 2-21COlapException class 3-39 to 3-40

Get_m_code() 3-40Get_m_reason() 3-40list of members 3-39

COlapObject class 1-8, 3-41 to 3-45GetApplication() 3-43GetParent() 3-44GetRefCount() 3-44GetType() 3-45Get_m_application() 3-42Get_m_iparent() 3-42Get_m_metabase() 3-43list of members 3-41

COleCollection class 1-8,3-46 to 3-58

AddItem() 3-49GetCount() 3-50GetElementIndex() 3-50GetItem() 3-51GetNames() 3-51Get_m_count() 3-49IGetItem() 3-52IMakeNth() 3-53IRemoveAll() 3-53


list of members 3-47MakeFirst() 3-54MakeLast() 3-54MakeNth() 3-55RemoveAll() 3-56RemoveItem() 3-57Remove() 3-55Swap() 3-58

Collectiondescribed 1-5member objects in a

counting 3-49, 3-50rearranging 3-53, 3-54, 3-55,

3-58removing 3-53, 3-55, 3-56, 3-57retrieving index for 3-50retrieving names for 3-51retrieving pointers to 3-51, 3-52

of Extension objects 3-109of Filter objects 3-132of FilterElement objects 3-128of Folder objects 3-146of MetaCube objects 3-224of Query objects 3-227of QueryBackJob objects 3-274of QueryCategory objects 3-277

rearranging 3-280, 3-281, 3-283of QueryItem objects 3-311

rearranging 3-314, 3-315, 3-316of Summary objects 3-317

rearranging 3-321, 3-322, 3-323Column breaks

sorting within 3-203Columns

in a CQueryCube objectdeleting 3-69inserting 3-90orientation of values 3-79, 3-80,

3-81in a MetaCube object

counting 3-211sorting 3-215, 3-220sorting within 3-204specifying 3-200

suppressing duplicate valueswithin 3-207

Commit() 3-5

Comparingvalue of CDimKey objects 3-24,

3-25, 3-26Configuration of Metabase

parameters, retrieving 3-162Confirming

changes to a database 3-5Connect() 3-156Constants

cell type 3-199client type 3-161data skipping 3-165defined in header file 1-11filter element 3-125frequency 3-260, 3-268job status 3-270orientation 3-239, 3-247, 3-257,

3-290sort direction 3-204, 3-206, 3-208,

3-292, 3-333summarization 3-319, 3-327vendor 3-163verification 3-36, 3-38

Constructinga CDimKey object 3-20

Copyinga MetaCube object 3-194

Copy() 3-194Cost of query

determining 3-242Counting

cells in a QueryCube 3-71columns in a MetaCube

object 3-211dimensions in a QueryCube 3-71Filter objects 3-136objects in a collection 3-49, 3-50pages

in a MetaCube object 3-214in a QueryCube 3-73

QueryCategory objectsreturning values to a

QueryCube 3-82rows

and columns on a QueryCubepage 3-86

in a MetaCube object 3-214retrieved by calling Fetch() 3-97

CParseNodeclass 3-59 to 3-63

list of members 3-61m_children 3-62m_number_val 3-62m_state 3-62m_string_val 3-63m_type 3-63

objects 2-11, 3-59children of 3-62for QueryCategory

objects 3-291for QueryItem objects 3-304forming a hierarchical tree,

illustrated 3-60numeric value 3-62string value 3-63type 3-63

CPlugInclass 3-64 to 3-65

list of members 3-64m_dll 3-65m_extensions 3-65

objectencapsulated in a Snap-In 3-107

CQueryCubeclass 3-66 to 3-94

DeleteCell() 3-69DeleteColumn() 3-69DeletePage() 3-70DeleteRow() 3-70GetCellItemIndex() 3-76GetCellKey() 3-78GetCell() 3-74GetColDimIndexes() 3-79GetColDims() 3-80GetColLabels() 3-81GetDimCounts() 3-82GetPageDimIndexes() 3-83GetPageDims() 3-84GetPageLabels() 3-85GetPageSize() 3-86GetRowDimIndexes() 3-87GetRowDims() 3-88GetRowLabels() 3-89Get_m_cellcount() 3-71Get_m_dimcount() 3-71Get_m_dimonly() 3-72Get_m_iparent() 3-72

Index 3

Get_m_numpages() 3-73InsertColumn() 3-90InsertPage() 3-91InsertRow() 3-92list of members 3-67SetCell() 3-93

objectretrieving 3-240

CreateNew() 3-156Creating

the DSS System 3-156CSelect

class 3-95 to 3-97Define() 3-96Fetch() 3-97list of members 3-95RowCount() 3-97

objectsdefining their data formats 3-96destroying 3-6retrieving data from 3-97

C++ programming interface 1-3

DData

in a MetaCube objectretrieving 3-222, 3-223

skippingconstants 3-165specifying 3-165

sourcefor query, specifying 3-238

type constants 3-8, 3-10types

standard 1-10Database

connectionclass embodying 3-3comparing to query

definition 3-248disconnecting 3-157logging in 3-156, 3-157, 3-169optimization, setting 3-171schemas 3-180vendor

constants 3-163identifying 3-163

Datecurrent, retrieving 3-175of last metadata

modification 3-168query

was last changed 3-248DBLogin() 3-157DBLogout() 3-157Define() 3-96Defining

format of data in CSelectobject 3-96

DeleteCell() 3-69DeleteColumn() 3-69DeleteFilter() 3-114DeleteJob() 3-264DeleteMetaModel() 3-158DeletePage() 3-70DeleteQuery() 3-159, 3-234DeleteRow() 3-70DeleteString() 3-5Deleting

DSS system from metadata 3-158filters 3-114from a QueryCube

cells 3-69columns 3-69pages 3-70rows 3-70

querydefinition from database 3-234from metadata 3-159

QueryBackJob 3-264strings stored in a database 3-5

Derived classes 1-8Destroying

a CSelect object 3-6Determining if

filter definition haschanged 3-118

Metabase object has connected todatabase 3-164

metadata object definition haschanged 3-35

querydefinition matches database

connection 3-248filters on time 3-253is saved to database 3-241

reports measure data 3-72results reside in memory 3-243

QueryCategory expression hasbeen parsed 3-291

QueryItem expression has beenparsed 3-304

user has privilegesto change filter 3-118

Development environment,identifying 3-161

Dimension keys 3-18 to 3-27comparing 3-24, 3-25, 3-26grouping 3-21retrieving

for a cell in a QueryCube 3-78sorting 3-22string value of 3-23

DimensionElement object 3-287Dimensions

in a CQueryCube objectcounting 3-71

objectidentifying in DSS System 3-175

Directory where MetaCube isinstalled

identifying 3-170Disconnecting

from a database 3-157DispIsA() macro 1-13DLL file

handle 3-65, 3-104DLLMAIN() function 2-6DoSQL() 3-160Double data type 1-10DrillDataSources collection

for queryretrieving 3-244

DSS Systemclosing 3-156creating 3-156date of last update 3-168deleting from metadata 3-158names, retrieving 3-177opening 3-187saving changes 3-188saving under new name 3-188


EEnabling

an extension 3-105EndSelect() 3-6Error

codedefined 1-10retrieving 3-40returned by server 3-265

description, retrieving 3-40handling 3-39margins

for a cell, retrieving 3-209for a query 3-196for a query, specifying 3-237

message returned by server 3-265results

in tab-delimited form 3-195ErrorSpreadClip() 3-195ErrorVBArray() 3-196error.h file 1-10, 3-40ExecuteStmt()

requiringno runtime arguments 3-7runtime arguments 3-8

Executinga query automatically 3-236an SQL statement

non-SELECT 3-7, 3-8, 3-160that performs a query 3-16

Extensionargument types

listed 3-106retrieving list of 3-102

argumentschanging description 2-6changing types 2-8listed 3-106retrieving list of 3-101validating 2-9 to 2-12

class 3-98 to 3-108GetArguments() 3-101GetArgumentTypes() 3-102GetFileName() 3-103GetFunctions() 3-103GetTypes() 3-104list of members 3-99m_dll 3-104

m_enabled 3-105m_fileName 3-105m_iarguments 3-106m_iargumenttypes 3-106m_ifunctions 3-106m_itypes 3-107m_plugin 3-107OnEnabledChanged() 3-107OnFinalRelease() 3-108RefreshList() 3-108

Descriptiontext box in SDK Extension

Wizard 2-5file name 3-105

retrieving 3-103functions

listed 3-106retrieving list of 3-103retrieving list of affected

classes 3-104Name

text box in SDK ExtensionWizard 2-5

objectadding to a collection 3-110removing from a

collection 3-111process code

creating 2-12 to 2-17sample 2-3

code for 2-21Extensions

class 3-109 to 3-111Add() 3-110list of members 3-109OnFinalRelease() 3-110Remove() 3-111

in a Snap-In 3-28, 3-65needed for a query 3-288, 3-300object

identifying 3-176registered, retrieving list of 3-166

extensions.h file 2-8

FFactTables object

identifying 3-176

FetchCellError() 3-198FetchCellType() 3-199FetchCell() 3-197Fetch() 3-97Filter

changing name of 3-120, 3-144class 3-112 to 3-120

DeleteFilter() 3-114GetFilterElements() 3-116GetFolder() 3-116GetName() 3-117GetOwner() 3-117GetSaved() 3-118GetUpdatable() 3-118Get_m_enabled() 3-114Get_m_group() 3-115Get_m_iparent() 3-115list of members 3-113OnEnabledChanged() 3-119OnGroupChanged() 3-119SaveAs() 3-120Save() 3-119SetName() 3-120

determining ifdefinition has changed 3-118user can change 3-118

element constants 3-125objects

adding to a collection 3-133,3-134, 3-135

counting 3-136deleting 3-114grouping 3-115removing from a

collection 3-138retrieving indexes for 3-137retrieving names of 3-117,

3-141, 3-143parameters

assigning values 3-258undefined 3-251

preventing application to aquery 3-114

retrieving owners of 3-117saving 3-119

with a name 3-120FilterElement

class 3-121 to 3-127GetFilterOn() 3-124

Index 5

GetFilterType() 3-125GetObject() 3-126Get_m_iparent() 3-123Get_m_operand() 3-123Get_m_operator() 3-124list of members 3-122SetFilterOn() 3-127

objectsadding to a collection 3-129removing from a

collection 3-131FilterElements

class 3-128 to 3-131Add() 3-129Get_m_iparent() 3-131list of members 3-128OnOperandChanged() 3-126OnOperatorChanged() 3-126Remove() 3-131

retrievingfor a filter 3-116

Filteringobject type used for 3-125object used for 3-126on time

in a query 3-253operator used for 3-124values used for 3-123, 3-124

setting 3-127Filters

class 3-132 to 3-138AddDefault() 3-133AddNewFilter() 3-134AddSave() 3-135GetCountGroup() 3-136GetItemGroup() 3-137Get_m_iparent() 3-136list of members 3-132Remove() 3-138

collectionapplied to a query 3-245

Folderclass 3-139 to 3-145

GetFilterNames() 3-141GetFolders() 3-142GetFullPathName() 3-142GetName() 3-143GetQueryNames() 3-143list of members 3-140

RenameFilter() 3-144RenameQuery() 3-145SetName() 3-145

containing a filterretrieving 3-116

containing a queryretrieving 3-246

naming 3-145objects

adding to a collection 3-148removing from a

collection 3-149retrieving 3-142retrieving path to 3-142

Folders class 3-146 to 3-149Add() 3-148Get_m_iparent() 3-148list of members 3-147Remove() 3-149

Format of a MetaCubesaving 3-202

Formatting commandsfor columns or rows

in a MetaCube object 3-213for numeric data 3-301, 3-306

changing 3-309Frequency

constants 3-260, 3-268of execution

for QueryBackJob 3-268Functions included in extension

list of 3-106FunctionType of CParseNode

object 3-63

Ggenclr() macro 1-13Get and Set

pairs of functions 1-16GetApplication() 3-43GetArguments() 3-101GetArgumentTypes() 3-102GetArrayValues() 3-335GetCellError() 3-209GetCellItemIndex() 3-76GetCellKey() 3-78GetCellType() 3-210

GetCell() 3-208CQueryCube member

function 3-74MetaCube member

function 3-208GetColDimIndexes() 3-79GetColDims() 3-80GetColLabels() 3-81GetColumns()

CDb member function 3-10MetaCube member

function 3-211GetCost() 3-242GetCountGroup() 3-136GetCount() 3-50GetCurrentAttribute() 3-212GetCurrentData() 3-243GetCurrentTime() 3-175GetDataSources()

CDb member function 3-11GetDimCounts() 3-82GetDimensions() 3-175GetDirty() 3-35GetDrillDataSources() 3-244GetElementIndex() 3-50GetErrorCode() 3-265GetErrorText() 3-265GetExecutionTime() 3-245GetExtensions() 3-176GetFactTables() 3-176GetFileName() 3-103GetFilterElements() 3-116GetFilterNames() 3-141GetFilterOn() 3-124GetFilters() 3-245GetFilterType() 3-125GetFolders() 3-142GetFolder()

Filter member function 3-116Query member function 3-246

GetFormatStrings() 3-213GetFormatString() 3-306GetFullPathName()

Folder member function 3-142GetFunctions() 3-103GetItemGroup() 3-137GetItemOrientation() 3-247


GetItem()COleCollection member

function 3-51QueryItem member

function 3-307GetJobID() 3-266GetLastUpdate() 3-248GetLive() 3-248GetMaximumExceeded() 3-249GetMetaCubes() 3-249GetMetaModelNames() 3-177GetNames() 3-51GetName() 3-307

Filter member function 3-117Folder member function 3-143Query member function 3-250QueryBackJob member

function 3-266QueryCategory member

function 3-293GetObject() 3-126

QueryCategory memberfunction 3-294

QueryItem memberfunction 3-308

GetOwner() 3-117GetPageDimIndexes() 3-83GetPageDims() 3-84GetPageLabels()

CQueryCube function 3-85MetaCube function 3-213

GetPageSize() 3-86GetPages() 3-214GetParameterObject() 3-250GetParameterOperator() 3-251GetParameters() 3-251GetParent()

COlapObject memberfunction 3-44

Metabase member function 3-177GetPriority() 3-267GetPublicUser() 3-178GetQueries() 3-178GetQueryBackJobs() 3-179GetQueryCategories() 3-252GetQueryCategory() 3-328GetQueryItems() 3-252GetQueryNames() 3-143GetRecurType() 3-268

GetRefCount() 3-44GetRootFolder() 3-179GetRowDimIndexes() 3-87GetRowDims() 3-88GetRowLabels() 3-89GetRows() 3-214GetSaved() 3-118GetSchemas() 3-180GetSize() 3-269GetSortColumn() 3-215GetSQL() 3-253GetStartTime() 3-269GetStatus() 3-270GetStopTime() 3-271GetString() 3-12GetSubmitTime() 3-271GetSummaries() 3-216GetSystemMessages() 3-180GetTabbedValues() 3-335GetTables() 3-13GetTargetStart() 3-272GetTimeFiltered() 3-253GetTypes() 3-104GetType() 3-45GetUniqueID() 3-181GetUpdatable() 3-118GetUsers() 3-14GetValue() 3-216GetVerified() 3-36GetVerifyResults() 3-37Get_m_ functions

explained 1-16Get_m_accuracy() 3-235

related verificationfunction 3-254

Get_m_application() 3-42Get_m_author() 3-235Get_m_autoRefresh() 3-236Get_m_category() 3-287, 3-291Get_m_cellcount() 3-71Get_m_clientType() 3-161


Get_m_code() 3-40Get_m_column() 3-200


Get_m_confidence() 3-237related verification

function 3-254Get_m_configuration() 3-162


Get_m_connectDatabase() 3-163related verification

function 3-182Get_m_connected() 3-164Get_m_connectString() 3-164


Get_m_count() 3-49Get_m_dataSkip() 3-165


Get_m_dataSource() 3-238related verification

function 3-254Get_m_db() 3-166Get_m_dimcount() 3-71Get_m_dimonly() 3-72Get_m_enabled() 3-114


Get_m_explain() 3-167related verification

function 3-183Get_m_extensions()

Metabase member function 3-166QueryItem member

function 3-300Get_m_extension() 3-288Get_m_formatString() 3-301Get_m_group() 3-115


Get_m_iparent()COlapObject member

function 3-42CQueryCube member

function 3-72Filter member function 3-115FilterElement member

function 3-123FilterElements member

function 3-131Filters member function 3-136

Index 7

Folders member function 3-148MetaCube member

function 3-200MetaCubes member

function 3-225Queries member function 3-228Query member function 3-238QueryBackJob member

function 3-264QueryBackJobs member

function 3-275QueryCategories member

function 3-280QueryCategory member



function 3-313Summaries member

function 3-321Summary member function 3-326ValueList member function 3-332

Get_m_itemOrientation() 3-239Get_m_item() 3-302, 3-304Get_m_lastUpdate() 3-168Get_m_localMetamodelFile() 3-168


Get_m_login() 3-169related verification

function 3-184Get_m_maxRows() 3-332


Get_m_maxTotalFetches() 3-169Get_m_metabase() 3-43Get_m_metacube_path() 3-170Get_m_name() 3-303

Metabase member function 3-170related verification

function 3-185MetaCube member

function 3-201related verification

function 3-217Query member function 3-240QueryCategory member

function 3-289

Get_m_numpages() 3-73Get_m_object()



Get_m_operand() 3-123related verification

function 3-126Get_m_operator() 3-124


Get_m_optimization() 3-171related verification

function 3-185Get_m_orientation() 3-290


Get_m_page() 3-201Get_m_parsed()



Get_m_parse()QueryCategory member


function 3-304Get_m_password() 3-172


Get_m_pDQPriority() 3-173related verification

function 3-185Get_m_qcube() 3-240Get_m_queryCategory() 3-326Get_m_reason() 3-40Get_m_referenceCount() 3-241Get_m_row() 3-202


Get_m_saved() 3-241Get_m_schema() 3-174


Get_m_scratch() 3-202Get_m_sortColumnBreaks() 3-203


Get_m_sortColumn-Direction() 3-204


Get_m_sortDirection() 3-292related verification

function 3-295Get_m_sortRowBreaks() 3-205


Get_m_sortRowDirection() 3-206related verification

function 3-219Get_m_sort() 3-333


Get_m_subset() 3-334related verification

function 3-336Get_m_summaryType() 3-327


Get_m_suppressDialogs() 3-174Get_m_suppressDuplicates() 3-207


Get_m_type()QueryCategory member


function 3-305Grouping

CDimKey objects 3-21within a query

defining 3-287

HHash() 3-21Header files 1-10

error.h 1-10metacons.h 1-11sdk.h 1-12

Hierarchy chartsexplained 1-8


Hypercubeof data 3-66

IIdentifying

author of a query 3-235CDb object 3-166class to which object belongs 3-45database vendor 3-163development environment 3-161DSS Systems

Dimensions object 3-175FactTables object 3-176

folder holding a query 3-246Metabase collection of

Extensions object 3-176Query objects 3-178QueryBackJob objects 3-179Schema objects 3-180

ODBC data sources 3-164parent of a

COlapObject object 3-42, 3-44CQueryCube object 3-72Filter object 3-115FilterElement object 3-123FilterElements object 3-131Filters object 3-136Folders object 3-148MetaCube object 3-200MetaCubes object 3-225Queries object 3-228Query object 3-238QueryBackJob object 3-264QueryBackJobs object 3-275QueryCategories object 3-280QueryCategory object 3-288QueryItem object 3-302QueryItems object 3-313Summaries object 3-321Summary object 3-326ValueList object 3-332

public user 3-178QueryCategory object

included in filterdefinition 3-250

RootFolder object 3-179

SystemMessages objectfor Metabase object 3-180

IDispatchobject 3-181pointer

mapping 3-181IGetItem() 3-52IMakeNth() 3-53Inheritance 1-8Initialization file 3-98InsertColumn() 3-90Inserting

a column into a QueryCube 3-90a page into a QueryCube 3-91a row into a QueryCube 3-92

InsertPage() 3-91InsertRow() 3-92Instantiating

a query in metadata 3-186IRemoveAll() 3-53IsA() macro 1-12ItemJobID() 3-276

JJob ID

assigned by serverwhile processing

QueryBackJob 3-266Job status

constants 3-270of QueryBackJob 3-270

LLogging

into database 3-156, 3-157, 3-169,3-172

out from database 3-157Long data type 1-10

MMacro

clearing memory 1-13determining class

membership 1-12, 1-13

making an array of nulls 1-13making null pointer 1-14making null value 1-14

MakeFirst()COleCollection member




function 3-321MakeLast()

COleCollection memberfunction 3-54

QueryCategories memberfunction 3-281

QueryItems memberfunction 3-314


MakeNth()COleCollection member




function 3-322MAKENULLS() macro 1-13Maximum number of rows

returned by query 3-249returned from ValueList

object 3-332MCXSDK_ VERSION 3-64Measure data

reported by a query 3-72Measure object

used for query 3-302, 3-307changing 3-310

Memorymacro for clearing 1-13

Metabaseclass 3-150 to 3-188

CloseDSSSystem() 3-156Connect() 3-156CreateNew() 3-156DBLogin() 3-157

Index 9

DBLogout() 3-157DeleteMetaModel() 3-158DeleteQuery() 3-159DoSQL() 3-160GetCurrentTime() 3-175GetDimensions() 3-175GetExtensions() 3-176GetFactTables() 3-176GetlMetaModelNames() 3-177GetParent() 3-177GetPublicUser() 3-178GetQueries() 3-178GetQueryBackJobs() 3-179GetRootFolder() 3-179GetSchemas() 3-180GetSystemMessages() 3-180GetUniqueID() 3-181Get_m_clientType() 3-161Get_m_configuration() 3-162Get_m_connect-

Database() 3-163Get_m_connected() 3-164Get_m_connectString() 3-164Get_m_dataSkip() 3-165Get_m_db() 3-166Get_m_explain() 3-167Get_m_extensions() 3-166Get_m_lastUpdate() 3-168Get_m_localMetamodel-

File() 3-168Get_m_login() 3-169Get_m_maxTotal-

Fetches() 3-169, 3-249Get_m_metacube_path() 3-170Get_m_name() 3-170Get_m_optimization() 3-171Get_m_password() 3-172Get_m_pDQPriority() 3-173Get_m_schema() 3-174Get_m_suppress-

Dialogs() 3-174list of members 3-151ObjFromIDispatch() 3-181OnClientTypeChanged() 3-182OnConfiguration-

Changed() 3-182OnConnectDatabaseChanged()

3-182

OnConnectString-Changed() 3-183

OnDataSkipChanged() 3-183OnExplainChanged() 3-183OnLocalMetamodelFile-

Changed() 3-184OnLoginChanged() 3-184OnMetaSchemaChanged() 3-18

4OnNameChanged() 3-185OnOptimization-

Changed() 3-185OnPasswordChanged() 3-185OnPDQPriority-

Changed() 3-185OpenDSSSystem() 3-187OpenQueryStorage() 3-187OpenQuery() 3-186SaveAs() 3-188Save() 3-188

object 3-65retrieving 3-43

metacons.h file 1-11MetaCube

class 3-189 to 3-223ClearSorts() 3-194Copy() 3-194ErrorSpreadClip() 3-195ErrorVBArray() 3-196FetchCellError() 3-198FetchCellType() 3-199FetchCell() 3-197GetCellError() 3-209GetCellType() 3-210GetCell() 3-208GetColumns() 3-211GetCurrentAttribute() 3-212GetFormatStrings() 3-213GetPageLabels() 3-213GetPages() 3-214GetRows() 3-214GetSortColumn() 3-215GetSummaries() 3-216GetValue() 3-216Get_m_column() 3-200Get_m_iparent() 3-200Get_m_name() 3-201Get_m_page() 3-201Get_m_row() 3-202

Get_m_scratch() 3-202Get_m_sortColumn-

Breaks() 3-203Get_m_sortColumnDirection()

3-204Get_m_sortRowBreaks() 3-205Get_m_sortRow-

Direction() 3-206Get_m_suppress-

Duplicates() 3-207hierarchy, illustrated 1-6, 1-7library 1-8list of members 3-190OnColumnBreaks-

Changed() 3-218OnColumnChanged() 3-217OnColumnDirectionChanged()

3-218OnNameChanged() 3-217OnRowChanged() 3-218OnSortRowBreaks-

Changed() 3-219OnSortRowDirectionChanged()

3-219OnSuppressDuplicates-

Changed() 3-219SetSortColumn() 3-220SetSortRow() 3-221ToSpreadClip() 3-222ToVBArray() 3-223

engine, identifying 3-42, 3-43objects

adding to a collection 3-225clearing sorts from 3-194copying 3-194removing from a

collection 3-226MetaCubes

class 3-224 to 3-226Add() 3-225Get_m_iparent() 3-225list of members 3-224Remove() 3-226

collectionassociated with query 3-249

Metacube.ini file 3-98, 3-105, 3-162MetamodelFile parameter 3-168MetamodelSchema

parameter 3-174


Metadataclasses 1-4

illustrated 1-7file, storing local copy of 3-168objects

determining if definitions havechanged 3-35

verifying 3-38retrieving schema from 3-174

m_arguments 3-29m_argumenttypes 3-30m_children 3-62m_dll

CPlugIn class data member 3-65Extension class data

member 3-104m_enabled 3-105

related notificationfunction 3-107

m_extensions 3-65m_fileName 3-105m_group 3-21m_iarguments 3-106m_iargumenttypes 3-106m_ifunctions 3-106m_itypes 3-107m_number_val 3-62m_plugin 3-107m_processitem 3-31m_selfsort 3-22m_sortval 3-22m_state 3-62m_string 3-23m_string_val 3-63m_type 3-31, 3-63m_validate 3-32

NName

of file containing compiledextension code 3-105

retrieving for aDSS System 3-170MetaCube object 3-201Query object 3-240QueryBackJob object 3-266

NameType of CParseNodeobject 3-63

Naminga filter 3-120, 3-144a folder 3-145a query 3-145restrictions

for objects 1-9Null

pointermacro for making 1-14

valuearray, macro for making 1-13macro for making 1-14

NULLP() macro 1-14NULLV() macro 1-14Number of Arguments

text box in SDK ExtensionWizard 2-5

NumberType of CParseNodeobject 3-63

Numericdata

formatting 3-301, 3-306, 3-309value

of a CParseNode object 3-62

OObject

adding to a collection 3-49hierarchies 1-4, 1-5naming restrictions 1-9used to create

QueryCategoryexpression 3-289, 3-294

QueryItem expression 3-303,3-308

ObjFromIDispatch() 3-181ODBC data sources

identifying 3-164retrieving 3-11

OLEautomation 1-3, 1-4programming interface 1-3reference count

retrieving 3-44SafeArray 3-335

OnAccuracyChanged() 3-254OnClientTypeChanged() 3-182OnColumnBreaksChanged() 3-218OnColumnChanged() 3-217OnColumnDirection-

Changed() 3-218OnConfidenceChanged() 3-254OnConfigurationChanged() 3-182OnConnectDatabase-

Changed() 3-182OnConnectStringChanged() 3-183OnDataSkipChanged() 3-183OnDataSourceChanged() 3-254OnEnabledChanged() 3-107, 3-119OnExplainChanged() 3-183OnFinalRelease() 3-108, 3-110OnGroupChanged() 3-119OnLocalMetamodelFile-

Changed() 3-184OnLoginChanged() 3-184OnMaxRowsChanged() 3-336OnMetaSchemaChanged() 3-184OnNameChanged() 3-185, 3-217OnOperandChanged() 3-126OnOperatorChanged() 3-126OnOptimizationChanged() 3-185OnOrientationChanged() 3-295OnPasswordChanged() 3-185OnPDQPriorityChanged() 3-185OnRowChanged() 3-218OnSortChanged() 3-336OnSortDirectionChanged() 3-295OnSortRowBreaksChanged() 3-219OnSortRowDirection-

Changed() 3-219OnSubsetChanged() 3-336OnSummaryTypeChanged() 3-329OnSuppressDuplicatesChanged()

3-219OpenDSSSystem() 3-187Opening

a DSS System 3-187OpenQueryStorage() 3-187OpenQuery() 3-186Operator

for undefined parameterretrieving 3-251

operator<() 3-25operator==() 3-26

Index 11

operator>() 3-24Orientation

constants 3-239, 3-247, 3-257,3-290

of measures returned byquery 3-239, 3-247, 3-257

of values in a QueryCube 3-82of values returned by

QueryCategory 3-290Overloaded operator function

for comparing CDimkeyobjects 3-24, 3-25, 3-26

PPages

in a MetaCube objectcounting 3-214specifying 3-201

in a QueryCubecounting 3-73deleting 3-70determining size 3-86inserting 3-91orientation of values 3-83, 3-84,

3-85Parameters applied to a query

clearing 3-234Parent object 1-5

identifying forCOlapObject 3-42, 3-44CQueryCube object 3-72Filter object 3-115FilterElement object 3-123FilterElements object 3-131Filters object 3-136Folders object 3-148MetaCube object 3-200MetaCubes object 3-225Queries object 3-228Query object 3-238QueryBackJob object 3-264QueryBackJobs object 3-275QueryCategories object 3-280QueryCategory object 3-288QueryItem object 3-302QueryItems object 3-313Summaries object 3-321

Summary object 3-326ValueList object 3-332

Passwordretrieving 3-172

PDQ Prioritysetting 3-173

plugin.h 3-64Preventing

filter from being applied to aquery 3-114

Priority assigned to QueryBackJobby server 3-267

Process performed by extensioncreating 2-12 to 2-17

Process() functionin .cpp file 2-12 to 2-17, 3-31

understanding 2-12Public user

identifying 3-178PutString() 3-15

QQueries

class 3-227 to 3-229Add() 3-228Get_m_iparent() 3-228list of members 3-227Remove() 3-229

executing SQL statements thatperform 3-16

objectidentifying 3-178

Querychanging name of 3-145class 3-230 to 3-260

ClearParameters() 3-234DeleteQuery() 3-234GetCost() 3-242GetCurrentData() 3-243GetDrillDataSources() 3-244GetExecutionTime() 3-245GetFilters() 3-245GetFolder() 3-246GetItemOrientation() 3-247GetLastUpdate() 3-248GetLive() 3-248GetMaximumExceeded() 3-249

GetMetaCubes() 3-249GetName() 3-250GetParameterObject() 3-250GetParameterOperator() 3-251GetParameters() 3-251GetQueryCategories() 3-252GetQueryItems() 3-252GetSQL() 3-253GetTimeFiltered() 3-253Get_m_accuracy() 3-235Get_m_author() 3-235Get_m_autoRefresh() 3-236Get_m_confidence() 3-237Get_m_dataSource() 3-238Get_m_iparent() 3-238Get_m_itemOrientation() 3-239Get_m_name() 3-240Get_m_qcube() 3-240Get_m_referenceCount() 3-241Get_m_saved() 3-241OnAccuracyChanged() 3-254OnConfidenceChanged() 3-254OnDataSourceChanged() 3-254Retrieve() 3-255SaveAs() 3-256SaveStorage() 3-256Save() 3-255SetItemOrientation() 3-257SetName() 3-257SetParameters() 3-258SetSQL() 3-259Submit() 3-260

costdetermining 3-242

definitiondeleting from database 3-234saving 3-255saving to a storage object 3-256saving under a name 3-256

deleting from metadata 3-159determining if saved to

database 3-241error margins 3-196grouping, defining 3-287instantiating in metadata 3-186object

adding to a collection 3-228name, changing 3-257name, retrieving 3-250


removing from acollection 3-229

retrieving name 3-143saved in storage object 3-187

resultsresiding in memory 3-243retrieving 3-273

submitting for processing 3-260summarizations 3-327time needed to execute 3-245

QueryBackJobclass 3-261 to 3-273

DeleteJob() 3-264GetErrorCode() 3-265GetErrorText() 3-265GetJobID() 3-266GetName() 3-266GetPriority() 3-267GetRecurType() 3-268GetSize() 3-269GetStartTime() 3-269GetStatus() 3-270GetStopTime() 3-271GetSubmitTime() 3-271GetTargetStart() 3-272Get_m_iparent() 3-264list of members 3-262RefreshStatus() 3-272Retrieve() 3-273

deleting 3-264object 3-260

in a collection, retrieving 3-276values, obtaining the

current 3-272, 3-275QueryBackJobs

class 3-274 to 3-276Get_m_iparent() 3-275ItemJobID() 3-276list of members 3-274RefreshStatus() 3-275


QueryCategoriesclass 3-277 to 3-283

Add() 3-279Get_m_iparent() 3-280list of members 3-278MakeFirst() 3-280MakeLast() 3-281

MakeNth() 3-281Remove() 3-282Swap() 3-283

collectionfor a query 3-252

returning values to a QueryCubecounting 3-82in column orientation 3-79,

3-80, 3-81in page orientation 3-83, 3-84,

3-85in row orientation 3-87, 3-88,

3-89QueryCategory

class 3-284 to 3-296GetName() 3-293GetObject() 3-294Get_m_category() 3-287Get_m_extension() 3-288Get_m_iparent() 3-288Get_m_name() 3-289Get_m_object() 3-289Get_m_orientation() 3-290Get_m_parsed() 3-291Get_m_parse() 3-291Get_m_sortDirection() 3-292Get_m_type() 3-293list of members 3-285OnOrientationChanged() 3-295OnSortDirectionChanged() 3-2

95SetName() 3-296

expression 3-291classifying 3-293defining grouping in

query 3-287object 2-11

adding to a collection 3-279defining grouping in a

query 3-326, 3-328, 3-329included in filter

definition 3-250label 3-293, 3-296moving in a collection 3-280,

3-281name 3-289removing from a

collection 3-282retrieving the current 3-212

sorting values 3-292specifying order in

collection 3-281swapping position in

collection 3-283QueryCube. See CQueryCube.QueryItem

class 3-297 to 3-310GetFormatString() 3-306GetItem() 3-307GetName() 3-307GetObject() 3-308Get_m_extensions() 3-300Get_m_formatString() 3-301Get_m_iparent() 3-302Get_m_item() 3-302Get_m_name() 3-303Get_m_object() 3-303Get_m_parsed() 3-304Get_m_parse() 3-304Get_m_type() 3-305list of members 3-298SetFormatString() 3-309SetItem() 3-310SetName() 3-310

expression 3-302, 3-304, 3-307changing 3-310classifying 3-305

name 3-303, 3-307changing 3-310

object 2-11adding to a collection 3-313moving in a collection 3-314removing from a

collection 3-315specifying order in

collection 3-315swapping position in

collection 3-316QueryItems

class 3-311 to 3-316Add() 3-313Get_m_iparent() 3-313list of members 3-312MakeFirst() 3-314MakeLast() 3-314MakeNth() 3-315Remove() 3-315Swap() 3-316

Index 13

collectionfor a query 3-252

RRearranging

objects in a collection 3-53, 3-54,3-55, 3-58

Recordingquery information 3-167

RefreshList() 3-108RefreshStatus() 3-261

QueryBackJob memberfunction 3-272

QueryBackJobs memberfunction 3-275

RemoveAll() 3-56RemoveItem() 3-57Remove() 3-55

Extensions memberfunction 3-111

FilterElements memberfunction 3-131

Filters member function 3-138Folders member function 3-149MetaCubes member

function 3-226Queries member function 3-229QueryCategories member



function 3-323Removing

from a collectionExtension objects 3-111Filter objects 3-138FilterElement objects 3-131Folder objects 3-149MetaCube objects 3-226objects 3-53, 3-55, 3-56, 3-57Query objects 3-229QueryCategory objects 3-282QueryItem objects 3-315Summary objects 3-323

RenameFilter() 3-144RenameQuery() 3-145

Replacingan SQL statement for a

query 3-259Resource file

for project 2-6resource.h file 1-12Retrieve()

Query member function 3-255QueryBackJob member

function 3-273Retrieving

CIExtension object 3-288classes

to which extension functionsapply 3-104

configuration of Metabaseparameters 3-162

CParseNode objectfor QueryCategory object 3-291

CParseNode objectsfor QueryItem objects 3-304

CQueryCube object 3-240data in CSelect object 3-97date and time 3-175

query was last changed 3-248descriptions

of argument types in anextension function 3-102

of arguments in an extensionfunction 3-101

DrillDataSources collectionfor query 3-244

DSS System names 3-177error

codes 3-40descriptions 3-40margins for a cell 3-209

FilterElements objectassociated with filter 3-116

Filters collectionapplied to a query 3-245

Folder object 3-142containing a filter 3-116

from a MetaCube objectattribute names 3-213cell data types 3-210cell error values 3-198cell value 3-216cell values 3-208

column to be sorted 3-215data 3-222, 3-223formatting commands 3-213row to be sorted 3-215Summaries collection 3-216

from a QueryCubedimension keys for cell 3-78index for cell 3-76value of a cell 3-74

groupassociated with filter 3-115

indexfor Filter objects 3-137for object in a collection 3-50

information about a tableowned by a user or schema 3-10

list ofclasses to which extension

functions apply 3-104functions in an extension 3-103registered extensions 3-166tables owned by a user or

schema 3-13users or schemas 3-14

Metabase object 3-43MetaCubes collection

for query 3-249name of

DSS System 3-170file containing extension

code 3-103MetaCube object 3-201Query object 3-240

names ofFilter objects 3-117, 3-141Folder objects 3-143objects in a collection 3-51queries associated with a

folder 3-143object

type used for filtering 3-125used for filtering 3-126used to create QueryCategory

expression 3-289, 3-294used to create QueryItem

expression 3-303, 3-308ODBC data sources 3-11OLE reference count for an

object 3-44


operatorfor undefined parameter 3-251used for filtering 3-124

orientationof QueryCategory values 3-290

ownerof Filter object 3-117

path toFolder objects 3-142

pointersto objects in a collection 3-51,

3-52Query object name 3-250QueryBackJob object

current values 3-272, 3-275error code 3-265error message 3-265frequency 3-268from a collection 3-276job ID 3-266name 3-266priority 3-267results 3-273rows returned to client 3-269status 3-270time processing begins 3-269time processing

completes 3-271time requested for

processing 3-272time submitted 3-271

QueryCategoriescollection for a query 3-252

QueryCategory objectassociated with current query

value 3-212defining grouping in a

query 3-326, 3-328, 3-329label 3-293name 3-289returning values in column

orientation 3-79, 3-80, 3-81returning values in page

orientation 3-83, 3-84, 3-85returning values in row

orientation 3-87, 3-88, 3-89QueryItem object

name 3-303, 3-307

QueryItemscollection for a query 3-252

rows, maximum number 3-169SQL statement for a query 3-253string stored in a database 3-12subset of ValueList

contents 3-334undefined filter parameters

for query 3-251values used for filtering 3-123,

3-124verification results 3-36, 3-37

Rollback() 3-15RootFolder object 3-146

identifying 3-179Row

breakssorting within 3-205

in a MetaCube objectsorting 3-215, 3-221specifying 3-202

orientationof values in a QueryCube 3-87,

3-88, 3-89RowCount() 3-97Rows

in a MetaCube objectcounting 3-214sorting within 3-206, 3-208suppressing duplicate values

within 3-207in a QueryCube

deleting 3-70inserting 3-92

maximum number to beretrieved 3-169

from ValueList object 3-332retrieved with Fetch()

counting 3-97returned by QueryBackJob 3-269

SSample extension 2-3

code for 2-21Sample tables 3-235SaveAs() 3-120, 3-188, 3-256SaveStorage() 3-256

Save() 3-119, 3-188, 3-255Saving

a filter 3-119, 3-120changes to a DSS System 3-188DSS System

under a new name 3-188query definition 3-255

to a storage object 3-256under a name 3-256

SCell structure 1-15, 3-74, 3-93Scheduling daemon 3-261Schemas

for metadata tables,retrieving 3-174


retrieving a list of 3-14Scratch 3-202SDK Extension Wizard

accessing 2-4editing the template code 2-6types of user 3, 4using 2-3 to 2-20

Step 1 2-4Step 2 2-5

sdk.h file 1-12, 3-74, 3-93buffer sizes 1-14macros 1-12

DispIsA() 1-13genclr() 1-13IsA() 1-12MAKENULLS() 1-13NULLP() 1-14NULLV() 1-14

templated array types 1-15SelectStmt() 3-16, 3-95SET EXPLAIN 3-167SET OPTIMIZATION 3-171SET PDQPRIORITY 3-173SetCell() 3-93SetFilterOn() 3-127SetFormatString() 3-309SetFrom() 3-27SetItemOrientation() 3-257SetItem() 3-310SetName() 3-310

Filter member function 3-120Folder member function 3-145Query member function 3-257

Index 15


SetParameters() 3-258SetQueryCategory() 3-329SetSortColumn() 3-220SetSortRow() 3-221SetSQL() 3-259Setting

column in a MetaCube objectto be sorted 3-220

database optimization 3-171PDQ Priority 3-173row in a MetaCube object

to be sorted 3-221value of a cell in a

QueryCube 3-93values used for filtering 3-127

Snap-In 3-64editing code in 2-6extensions 3-28, 3-65generating a template 2-4

Sort direction constants 3-204,3-206, 3-208, 3-292, 3-333

SortingCDimKey objects 3-22values returned by

QueryCategory object 3-292ValueList object 3-333

within MetaCubecolumns 3-203, 3-204rows 3-205, 3-206, 3-208

SQL statementexecuting

non-SELECT 3-7, 3-8, 3-160to perform a query 3-16

for a queryreplacing 3-259retrieving 3-253transmitting 3-255

Status windowssuppressing 3-174

Storage object containing a Queryobject 3-187

Storinga string in a database 3-15

Stringdata type 1-10in a database

deleting 3-5

getting 3-12storing 3-15

table 2-6, 3-29value

of a CDimKey object 3-23of a CParseNode object 3-63

Submittinga query for processing 3-260

Submit() 3-260Summaries

class 3-317 to 3-323Add() 3-319Get_m_iparent() 3-321list of members 3-318MakeFirst() 3-321MakeLast() 3-322MakeNth() 3-322Remove() 3-323Swap() 3-323

collectionin a MetaCube object,

sorting 3-216Summarization constants 3-319,

3-327Summarizing

within query groupings 3-327Summary

class 3-324 to 3-329GetQueryCategory() 3-328Get_m_iparent() 3-326Get_m_queryCategory() 3-326Get_m_summaryType() 3-327list of members 3-325OnSummaryTypeChanged() 3-

329SetQueryCategory() 3-329

objects in a collectionadding 3-319removing 3-323re-ordering 3-321, 3-322swapping position 3-323

Suppressingduplicate values in rows or

columns 3-207MetaCube status windows 3-174

Swap()COleCollection member

function 3-58

QueryCategories memberfunction 3-283

QueryItems memberfunction 3-316


SystemMessages objectidentifying 3-180

TTab-delimited

data 3-222in a ValueList object 3-335

error results 3-195Tables

owned by a user or schemaretrieving a list of 3-13retrieving information

about 3-10Templated array types 1-15Time

current, retrieving 3-175needed to execute query 3-245query

was last changed 3-248QueryBackJob

is submitted 3-271processing begins 3-269processing finishes 3-271was requested 3-272

ToSpreadClip() 3-222ToVBArray() 3-223Transmitting

SQL statementfor a query 3-255

TupleType of CParseNodeobject 3-63

Type of CParseNode object 3-63

UUndoing

changes to a database 3-15Unique ID

obtaining for multi-threading 3-181


Usersof the SDK Extension Wizard 3, 4retrieving a list of 3-14

VValidate() function

in .cpp file 2-9 to 2-12, 3-32understanding 2-11

ValueListclass 3-330 to 3-336

GetArrayValues() 3-335GetTabbedValues() 3-335Get_m_iparent() 3-332Get_m_maxRows() 3-332Get_m_sort() 3-333Get_m_subset() 3-334list of members 3-331OnMaxRowsChanged() 3-336OnSortChanged() 3-336OnSubsetChanged() 3-336

objectdata, sorting 3-333described 1-9subset of contents 3-334translating into OLE

SafeArray 3-335translating into tab-delimited

data 3-335Variant array containing error

margin values 3-196Verification

constants 3-36, 3-38results

retrieving 3-36, 3-37Verifying

metadata definitions 3-38Verify() 3-38Virtual function 3-55Visual Basic 3-223

WWildcard 3-334

Symbols.cpp file 3-28

Arguments() function 2-6ArgumentTypes() function 2-8editing sample code 2-6generating a template 2-4Process() function 2-12 to 2-17Validate() function 2-9 to 2-12

.dll file 2-6

.mcx file 3-64, 3-65, 3-104, 3-107

Index 17

metacube sdk for snap-ins programmer's manual · sdk for snap-ins programmer’s manual...

Documents