Analytic Calculation Engine Classes

This chapter provides an overview of the Analytic Calculation Engine classes, and discuses:

• Using the Analytic Calculation Engine classes with Application Engine

• Running synchronously

• Error handling

• Data types for the Analytic Calculation Engine classes

• Scope of the Analytic Calculation Engine class objects

• Analytic Calculation Engine reference

Important! The Analytic Calculation Engine classes are not supported on IBM z/OS and Linux for IBM System z platforms.

Understanding the Analytic Calculation Engine Classes

PeopleSoft Analytic Calculation Engine comprises a calculation engine plus several PeopleTools features which enable application developers to define both the calculation rules and the display of calculated data within PeopleSoft applications for the purposes of multi-dimensional reporting, data editing and analysis.

More specifically, developers create analytic models in order to define the rules which are used to calculate data. Developers also create PeopleSoft Pure Internet Architecture pages with analytic grids in order to display the data within PeopleSoft applications. End users view, analyze and make changes to this data. When end users save their changes, PeopleSoft Analytic Calculation Engine recalculates the data and saves the calculated data to the database.

PeopleCode enables developers to manipulate analytic calculation data as follows:

• Use the Analytic Calculation Engine classes to either retrieve or specify data in an instance of an analytic model loaded into the system, and also to calculate (or recalculate) cube values.

• Use the Analytic Calculation Engine metadata classes to manipulate an analytic model definition. For example, you can add cubes to a cube collection or rename an existing user function for a model.

• Use the Analytic Grid classes to manipulate the display of analytic calculation data on a page.

• Use the Analytic Type classes to manipulate an analytic type definition. For example, you can specify a new analytic model for an analytic type definition.

See Also

Analytic Calculation Engine Metadata Classes

Analytic Grid Classes

Analytic Type Classes

PeopleTools 8.52: Analytic Calculation Engine

Using the Analytic Calculation Engine Classes with Application Engine

All Application Engine programs run on the application engine server. This means your program runs on the application engine server, not the analytic server.

PeopleSoft recommends that you put each of the following methods into its own step when you're creating an analytic calculation using a Application Engine program:

• AnalyticInstance Load method

• AnalyticInstance Unload method

• AnalyticInstance Copy method

• AnalyticInstance Delete method (in case of any readable/writable records in the analytic type)

• AnalyticModel Recalculate method

• CubeCollection SetData method

Also, with the Recalculate method, you should use the Commit after step option.

Running Synchronously

Some of the methods and functions associated with these classes have the option of being run asynchronously. When you run these asynchronously, and not from a Application Engine program, these methods and functions have additional functionality, that is, if the RenServer is configured, a window displays the PeopleSoft Analytic Calculation Engine execution status.

Using Trees

PeopleSoft Analytic Calculation Engine uses trees to establish hierarchies of a dimension's parent-child relationships. PeopleSoft Analytic Calculation Engine uses these hierarchies to:

• Calculate and display aggregated data to end users.

• Enable end users to navigate through data by performing such actions as expanding and collapsing nodes.

• Enable end users to drill down and drill up through data.

It is important to understand that PeopleSoft trees and hierarchies differ in the following manner: You create one tree for each dimension that requires a hierarchy. The analytic model uses that tree to create one hierarchy for one dimension.

Use the AttachTree method to attach a tree to a dimension, and use the DetachTree method to detach the tree from the dimension.

You should be aware of the following restrictions:

• Because the AttachTree method attaches a specific tree to an analytic instance, the system throws an error if the tree's name, setID or effective date is incorrect.

• You can attach only one tree to one dimension at a time.

• If the analytic instance is already loaded into the analytic server, the tree isn't attached until the analytic model is loaded.

• No aggregate data is displayed to the user after you use the DetachTree method.

• If your application loads the analytic model after the tree has been detached, the analytic model doesn't create a hierarchy for the dimension.

• If the analytic instance is already loaded into the analytic server, the DetachTree method isn't applied to the tree until the next time your application loads the analytic instance.

You can only attach a tree to an analytic model before the analytic instance

No aggregate data displayed to user after detach tree.

See Also

Creating Hierarchies

Error Handling

All the Analytic Calculation Engine classes throw PeopleCode exceptions for any fatal error that occurs in the execution of the operation. PeopleSoft recommends enclosing your analytic model programs in try-catch statements. This way, if your program catches the exception, the message set and message number that are associated with the exception object indicate the error.

Using the Messages Property

Use the Messages property to determine whether any errors occurred. The Messages property returns a multi-dimensional array. You can use the Len property of the array class to determine the length of the array. If the array has a length of 0, there are no errors.

Data Types for Analytic Calculation Engine Classes

Every PeopleSoft Analytic Calculation Engine object is declared as its own data type, that is, AnalyticModel objects are declared as type AnalyticModel, CubeCollection objects are declared as type CubeCollection, and so on.

The following are the data types for the PeopleSoft Analytic Calculation Engine classes:

• AnalyticInstance

• AnalyticModel

• CubeCollection

Scope of Analytic Calculation Engine Classes

The Analytic Calculation Engine objects can only be instantiated from PeopleCode.

These objects can be used anywhere you have PeopleCode, that is, in a Application Engine program, an application class, record field PeopleCode, and so on.

Analytic Calculation Engine objects can be of scope Local, Component, or Global.

Analytic Calculation Engine Classes Built-in Functions

CreateAnalyticInstance

GetAnalyticInstance

AnalyticInstance Class Methods

In this section, we discuss the AnalyticInstance methods. The methods are discussed in alphabetical order.

CheckAsyncStatus

Syntax

CheckAsyncStatus(OperationID)

Description

Use the CheckAsyncStatus method to determine the current state of the asynchronous methods, as well as the Load method when executed asynchronously.

Parameters

Returns

This method returns one of the following values:

See Also

CheckStatus, Load, Unload.

CheckStatus

Syntax

CheckStatus()

Description

Use the CheckStatus method to determine the current state of the analytic calculation engine.

Parameters

None.

Returns

This method returns one of the following values:

See Also

Load, Unload.

Copy

Syntax

Copy(NewID, ForceDelete&Record)

Description

Use the Copy method to copy all the data and metadata to a new analytic instance from the current analytic instance.

If the specified NewID exists, or any data for NewID exists, the data is not copied unless ForceDelete has been specified as true.

If a tree is attached to the existing analytic instance, all tree data is also copied to the new analytic instance.

In addition, the analytic instance and the tree information are not copied unless the record specified with the &Record parameter is populated with the existing analytic instance ID.

Parameters

Returns

None.

Example

&ai.Copy("MYTESTCOPY", True, &MyRecord);

See Also

Delete, Load, Unload.

Designing Analytic Type Definitions

Delete

Syntax

Delete(ForceUnload, &RecordRef)

Description

Use the Delete method to remove all the metadata related to the given analytic instance.

Every analytic type definition is defined with an application package that contains three methods: Create, Delete, and Copy. The values in &RecordRef are passed to the Delete method.

This method does not delete the analytic instance if the analytic instance is currently loaded. Specify ForceUnload as true to unload the analytic instance before deleting it.

Parameters

Returns

None.

Example

&ai.Delete(TRUE, &Record);

See Also

Unload

Designing Analytic Type Definitions

GetAnalyticModel

Syntax

GetAnalyticModel(Model.ModelName)

Description

Use the GetAnalyticModel method to return a reference to an AnalyticModel object.

Parameters

Returns

A reference to an AnalyticModel object or Null.

See Also

AnalyticModel Class Methods

Load

Syntax

Load(Sync, IdleTimeOut, Message.messagename)

Description

Use the Load method to load the AnalyticInstance object executing the method into the analytic server.

If this analytic instance is already loaded, this method fails.

When the analytic instance is loaded, if there are fields in the analytic type definition that haven't been selected but are mapped to a cube or dimension, an error message is logged to the analytic server log and the analytic instance load fails.

If there is a record in the analytic type definition that has none of its fields mapped to a cube or dimension, a warning message is logged to the analytic server log.

Parameters

Returns

A string. For asynchronous loads, this string is passed to the CheckAsyncStatus method.

This method returns one of the following values:

See Also

CheckAsyncStatus, Unload.

RunAsync

Syntax

RunAsync()

Description

Use the RunAsync method to specify if the analytic instance executing the method should be run in an asynchronous manner.

This method is used only to define the transaction in the analytic type definition in optimization. PeopleSoft Analytic Calculation Engine programs uses the Load method for defining synchronous or asynchronous operation.

Parameters

None.

Returns

None.

See Also

Configuring Analytic Type Transactions

RunSync

Syntax

RunSync()

Description

Use the RunSync method to specify if the analytic instance executing the method should be run in a synchronous manner.

This method is used only to define the transaction in the analytic type definition in optimization. PeopleSoft Analytic Calculation Engine programs uses the Load method for defining synchronous or asynchronous operation.

Parameters

None.

Returns

None.

See Also

Configuring Analytic Type Transactions

Terminate

Syntax

Terminate()

Description

Use the Terminate method to force the termination of an analytic instance loaded in an analytic server.

This method should only be used from PeopleCode running in a Application Engine program to cause an analytic instance loaded in an analytic server to be terminated.

Attempting to terminate an analytic instance that is not loaded or is loaded in a Application Engine process results in a PeopleCode exception.

Although the Terminate method returns instantly, it may take up to a minute before the analytic instance is actually terminated.

Parameters

None.

Returns

None.

See Also

Load, Unload.

Unload

Syntax

Unload()

Description

Use the Unload method to unload the analytic instance executing the method from the analytic server. After unloading the analytic instance, the analytic server process is restarted.

Parameters

None.

Returns

None.

Example

&ai.UnLoad();

See Also

Load

AnalyticInstance Class Properties

In this section, we discuss the AnalyticInstance properties. The properties are discussed in alphabetical order.

AnalyticType

Description

This property returns the name of the analytic type definition for this AnalyticInstance object as a string.

This property is read-only.

ID

Description

This property returns the analytic instance ID of this AnalyticInstance object as an integer.

This property is read-only.

Messages

Description

This property returns a multi-dimensional array of any, containing the messages that occurred.

The first dimension contains the message set number. The second dimension contains the message number. The third dimension contains the number of parameters in that message. The subsequent dimensions contain the values for the parameters. The maximum number of possible dimensions is 8.

After you access this property, only new messages are returned, that is, messages are only returned once.

This property is read-only.

See Also

RunSync

AnalyticModel Class Methods

In this section, we discuss the AnalyticModel methods. The methods are discussed in alphabetical order.

AddMember

Syntax

AddMember(DimName, MemberName)

Description

Use the AddMember method to add the specified dimension member to the specified dimension.

Parameters

Returns

None.

See Also

GetMembers, RenameMember.

AttachTree

Syntax

AttachTree(DimName, TreeName, SetID, UserKeyValue, EffDt, NodeName, OverrideRecord, DetailStartLvl, TreeDiscardLvl)

Description

Use the AttachTree method to attach a tree to a dimension. Only one tree can be attached to a dimension at a time. You can only attach a tree before the analytic instance is loaded.

Parameters

Returns

None.

See Also

DetachTree, GetTree.

Tree Classes

Understanding the Relationship of PeopleSoft Trees to Analytic Models

CalculateCube

Syntax

CalculateCube(CubeName[, Sync])

Description

Use the CalculateCube method to calculate the named cube in synchronous mode.

Parameters

Returns

None.

See Also

Running Synchronously, Recalculate.

DetachTree

Syntax

DetachTree(DimName)

Description

Use the DetachTree method to detach a tree from the specified dimension.

You can only attach a tree when the analytic instance is not loaded. This method fails if you try to detach a tree while the analytic instance is loaded.

Parameters

Returns

None.

See Also

AttachTree, GetTree.

Tree Classes

GetCubeCollection

Syntax

GetCubeCollection(CubeCollName)

Description

Use the GetCubeCollection method to return a reference to a CubeCollection object.

Parameters

Returns

A CubeCollection object if successful.

See Also

CubeCollection Class

GetCellProperties

Syntax

GetCellProperties(CubeName, &Node)

Description

Use the GetCellProperties method to get information about a cell.

Parameters

Returns

An array of string.

The four strings returned in the array are:

1. Cell type. Values are “Aggregate” or “Detail”

2. User function.

3. Dimension for aggregation, the dimension name.

4. Aggregation reason. Values are: “Dimension Level Override”, “Member Level Override”, “Cube Dimension Level Override”, “None.”

See Also

Array Class.

GetMembers

Syntax

GetMembers(DimName, DimFilter)

Description

Use the GetMembers method to return the names of the members in the specified dimension. You can specify a user function to be used as a filter for the dimension using DimFilter.

When filtering hierarchy nodes, if the parent member is filtered, all the child nodes are also filtered.

In order to filter the parent member if all of its children are filtered, the user function should be written such that for the parent node, apply the condition on all of its children, using the FORCHILDREN built-in function. If none of the children satisfy the condition, return zero from the user function, which filters the parent node.

Parameters

Returns

A two-dimensional array of any.

The first dimension contains the member names. The second dimension contains the parent of the member. The members are sorted in the hierarchy order.

If the dimension does not have a hierarchy, all members are returned as level one.

For example, if the dimension has the following members:

ALLREGIONS
   NORTH AMERICA
      USA
      CANADA
      MEXICO
   EUROPE
      FRANCE
      GERMANY
      ENGLAND
   ASIA	
      JAPAN
      CHINA

The GetMembers method returns the following:

If the total member is present in the metadata, it is returned as level zero.

See Also

AddMember, RenameMember.

GetTree

Syntax

GetTree(DimName)

Description

Use the GetTree method to return an array of string that contains information about the tree that is attached to the specified dimension.

Parameters

Returns

An array of string.

The array items have the following format:

1. TreeName

2. SetID

3. UserKeyValue

4. EffDt

5. BranchName

6. Override record name

7. DetailStartLvl

8. TreeDiscardLvl

See Also

AttachTree, DetachTree.

Tree Classes

Recalculate

Syntax

Recalculate(Sync)

Description

Use the Recalculate method to recalculates the loaded analytic model. If Sync is true, the transaction is synchronous, else it is performed asynchronously.

The Recalculate method always writes any changes to readable, readable and writable, as well as writable records to the database as specified by the analytic type definition.

If you are running in asynchronous mode, this method returns an optional string that contains the operation ID to be used with the CheckAsyncStatus property.

Parameters

Returns

A string.

See Also

CalculateCube, CheckAsyncStatus.

AnalyticModelDefn

RenameMember

Syntax

RenameMember(DimName, OrigMemberName, NewMemberName)

Description

Use the RenameMember method to rename a member in the specified dimension.

Parameters

Returns

None.

See Also

AddMember, GetMembers.

AnalyticModel Class Property

In this section, we discuss the AnalyticModel class property.

Messages

Description

This property returns a multi-dimensional array of any containing the messages that occurred during execution of the Recalculate method.

The first dimension contains the message set number. The second dimension contains the message number. The third dimension contains the number of parameters in that message. The subsequent dimensions contain the values for the parameters. The maximum number of possible dimensions is 8.

After you access this property, only new messages are returned, that is, messages are only returned once.

This property is read only.

See Also

Recalculate

CubeCollection Class

Instantiate a CubeCollection object using the AnalyticModel class GetCubeCollection method.

In cube collections, the total member behaves just as the root of the hierarchy. If it's present, it's displayed first in the list.

Filtering of members in a dimension in the cube collection is similar to filtering members using the AnalyticModel class GetMembers method. If you filter the parent node, the children of that node are filtered as well.

See AnalyticModel class: GetCubeCollection method.

CubeCollection Class Methods

In this section we discuss the CubeCollection class methods. The methods are described in alphabetical order.

CollapseNode

Syntax

CollapseNode(DimName, &Node)

Description

Use the CollapseNode method to collapse a node in the dimension specified by DimName.

Parameters

PRODUCTS     Fax Modem
REGION       East

Returns

None.

See Also

ExpandNode

DrillIntoNode

Syntax

DrillIntoNode(DimName, &Node)

Description

Use the DrillIntoNode method to display more data for the specified node and dimension. This is very similar to expanding, except that when you expand a node, the top level (node) is still present. When you drill into a node, the top level or levels are no longer displayed.

Parameters

PRODUCTS   Fax Modem
REGION     East

Returns

None.

See Also

DrillOutOfNode

DrillOutOfNode

Syntax

DrillOutOfNode(DimName, &Node)

Description

Use the DrillOutOfNode method to collapse the data that you just expanded.

Parameters

PRODUCTS     Fax Modem
REGION       East

Returns

None.

See Also

DrillIntoNode

ExpandNode

Syntax

ExpandNode(DimName, &Nodes, ExpandAll)

Description

Use the ExpandNode method to expand the nodes in the specified dimension.

Parameters

Returns

None.

Example

In the following example, both the Accounts and Dept dimensions have hierarchies.

Account             Dept
   
All Acoounts            All Depts
         | ---- 100                |  - ---- A
         |                         |
                | ---- 200                |------   B -| ---D
         |                     |
                |                      | --- E
                | ---- 300   

When the data is displayed, it will be as follows:

     All Accounts 
               All Depts
          100     
               All Depts
          200     
               All Depts
          300     
               All Depts

When you want to expand All Depts under Account 100 , use the following PeopleSoft Analytic Calculation Engine code:

     BAMCoordinate coord;
     coord.SetValue( "Account", "100");
     coord.SetValue("Dept" , "All Depts")
     ExpandNode("Dept", coord, false)

The result of this will have the following:

     All Accounts 
               All Depts
          100     
               All Depts
                        A
                        B
          200     
               All Depts
          300     
               All Depts

See Also

CollapseNode

GetData

Syntax

GetData(&DataRowset, StartRow, EndRow[, NetChanges])

Description

Use the GetData method to populate a rowset with data from the cube collection.

DataRowset is the rowset into which is put the data. If you specify an already instantiated rowset, the given rowset is populated with the data. If you specify a rowset that has not been instantiated, a new rowset is created, with the record field definition of the desired cube collection.

Parameters

Returns

None.

See Also

SetData, Messages.

Rowset Class

GetDimFilter

Syntax

GetDimFilter(DimName)

Description

Use the GetDimFilter method to return the name of the current user function (filter) used with the specified dimension.

Parameters

Returns

A string containing the name of the user function. If there is no filter applied to the dimension, this method returns an empty string.

See Also

SetDimFilter

GetDimSort

Syntax

GetDimSort(DimName)

Description

Use the GetDimSort to return the current sort settings on the specified dimension.

Parameters

Returns

An array of any. The array contains the same structure as the signature for the SetDimSort method.

See Also

SetDimSort

GetLayout

Syntax

GetLayout(&SlicerArray, &RowAxisArray, &ColumnAxisArray)

Description

Use the GetLayout method to return the current layout for the three axes, (slice, row, and column) on the specified dimension.

Parameters

Returns

None.

GetRowCount

Syntax

GetRowCount()

Description

Use the GetRowCount method to return the total number of rows in the cube collection.

The number of rows is a function of the hierarchy, that is, what is shown or not shown, and filtered values.

Parameters

None.

Returns

An integer.

See Also

GetDimension

GetSlice

Syntax

GetSlice(&SliceRecord)

Description

Use the GetSlice method to return the current slice values of all the dimensions.

Parameters

Returns

None.

See Also

SetSlice

SetData

Syntax

SetData(&DataRowset)

Description

Use the SetData method to populate the data in the cube collection with the data in the specified rowset.

The system extracts only changed values from the rowset, that is, values marked as updated. .

SetData method also writes the changes to the database for any record marked as writable or readable and writable in the analytic type definition, and mapped to the specified cube collection.

Parameters

Returns

None.

See Also

GetData

IsChanged

Rowset Class

SetDimensionOrder

Syntax

SetDimensionOrder(&FieldNames)

Description

Use the SetDimensionOrder method to specify the order of dimensions for this cube collection.

Parameters

Returns

None.

See Also

SetDimSort

SetDimFilter

Syntax

SetDimFilter(DimName, DimFilter)

Description

Use the SetDimFilter method to set a dimension filter for the specified dimension in the cube collection.

Parameters

Returns

None.

See Also

Understanding Dimensions

SetDimSort

Syntax

SetDimSort(DimName, IsAscending [, Key1, IsAscending2, Key2, IsAscending3, Key3])

Description

Use the SetDimSort method to specify the sorting order for the cube collection.

Key1, Key2and Key3 are optional parameters. If they are not specified, the sorting works as a name sort, that is, it sorts by the name of members in the given dimension, either in ascending or descending order.

If keys are specified, the keys values refer to the names of the cubes to be used as they key. The method orders the members of the dimension based on the value of the cubes for each member. The Boolean parameter IsAscending defines whether sorting should be in ascending or descending order. Up to three sort keys may be specified. Key1 is the primary sort key. Key2 is used to sub-sort any members that have the same key value under Key1, and so on.

The scope of this method is the same as the scope of the AnalyticModel object created in PeopleCode, that is, if the AnalyticModel object was declared with scope Global, this method would have a global scope as well, if it was declared as Local, it would have Local, and so on.

Specifying a null string for DimName or for keys one through three removes the current value as a sort value.

Parameters

Returns

None.

SetSlice

Syntax

SetSlice(&SliceRecord)

Description

Use the SetSlice method to specify a slice record for this cube collection.

Parameters

Returns

None.

See Also

GetSlice

ShowHierarchy

Syntax

ShowHierarchy(DimName, Show, ExpandToLevel)

Description

Use the ShowHierarchy method to either hide or display the cube collection hierarchy.

If there is a tree attached to the dimension, and Show is false, only the detail level members are shown in the Analytic grid. If Show is true, all members including nodes are shown.

When the hierarchy is hidden, the GetData method returns only leaf values. When the hierarchy is displayed, GetData returns node values and leaf values.

The ExpandToLevel parameter expands the hierarchy to the level specified. Level indexes start from 0 , the root level.

For example, if you specify ExpandToLevel as 1, the grid displays the total (root member) and all the detail members in a dimension with no tree attached.

In the following example, if you specify ExandToLevel as 2, the hierarchy would be displayed only to the quarter level, and not to the month level.

ALL_TIME
     2003
          Q1
               Jan
               Feb
               Mar
          Q2
               Apr
               May
               Jun
          Q3
               . . .
               . . .
          Q4
     2004
          Q1
          Q2
          Q3
          Q4

Parameters

Returns

None.

See Also

CollapseNode, ExpandNode, GetData.

UnsetDimFilter

Syntax

UnsetDimFilter(DimName)

Description

Use the UnsetDimFilter method to remove the filter on the specified dimension for the cube collection.

Parameters

Returns

None.

See Also

SetDimFilter

UnsetDimSort

Syntax

UnsetDimSort(DimName)

Description

Use the UnsetDimSort method to remove the sorting on the specified dimension for a cube collection. After using this method, the members are returned in the global member order as specified in the analytic model definition.

Parameters

Returns

None.

See Also

SetDimSort

CubeCollection Class Property

In this section we discuss the CubeCollection class property.

Messages

Description

This property returns a multi-dimensional array of any containing the messages that occurred during execution of the GetData, SetData, and CalculateCube methods.

The first dimension contains the message set number. The second dimension contains the message number. The third dimension contains the number of parameters in that message. The subsequent dimensions contain the values for the parameters. The maximum number of possible dimensions is 8.

After you access this property, only new messages are returned, that is, messages are only returned once.

This property is read-only.

See Also

GetData, SetData.

CalculateCube