PeopleTools 8.51 PeopleBook: PeopleCode API Reference

Analytic Grid Classes

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

The analytic grid in PeopleCode.
Using freeze column mode.
Error handling.
Data types of analytic grid objects.
Scope of analytic grid objects.
AnalyticGrid class reference.

Important! The analytic grid 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.

Analytic Calculation Engine Classes

Using the Analytic Grid in PeopleCode

The PeopleCode AnalyticGrid object is a reference to a page runtime object for the analytic grid. These particular page runtime objects aren’t present until the component is started.

Note. PeopleSoft builds a page grid one row at a time. Because the AnalyticGrid class applies to a complete grid, you can’t attach PeopleCode that uses the AnalyticGrid class to events that occur before the grid is built; the earliest event you can use is the page Activate Event.

If you’re using the analytic grid within a secondary page, the runtime object for the grid isn’t created until the secondary page is run. The grid object can’t be obtained until then, which means that the earliest PeopleCode event you can use to activate a grid that’s on a secondary page is the Activate event for the secondary page.

The attributes you set for displaying an analytic grid remain in effect only while the page is active. When you switch between pages in a component, you have to reapply those changes every time the page is displayed.

In addition, the Activate event associated with a page fires every time the page is displayed. Any PeopleCode associated with that Activate event runs, which may undo the changes you made when the page was last active. For example, if you hide a grid column in the Activate event, then display it as part of a user action, when the user tabs to another page in the component, then tabs back, the Activate event runs again, hiding the grid column again.

If a user at runtime hides a column of a grid, tabs to another page in the component, then tabs back to the first page, the page is refreshed and the grid column is displayed again.

You can use the rowset class methods and properties on analytic grid data. You can access the data loaded by the analytic grid by accessing a rowset object after the grid is populated.

Use the analytic grid classes to manipulate the display of an analytic grid—that is, one associated with PeopleSoft Analytic Calculation Engine data. If you want to manipulate a grid control, use the grid classes.

See Also

Using Freeze Column Mode

If you specify Freeze Column Mode for an analytic grid in Application Designer, the analytic grid isn't populated from the component buffer by default. It is your responsibility to write your application code so that it populates the rowset bound to the analytic grid.

Note. You should not be adding and deleting data from the analytic grid when you are not in Freeze Column Mode; this is an unsupported feature and might cause unexpected behavior.

In addition, no layout information is available, and there is no slicer, row, or column axis.

The following is an example of populating the analytic grid with data from a normal grid in Freeze Column Mode.

Local Rowset &RSAGRID;
Local Rowset &RSGrid;


/* Get the rowset associated with normal grid whose primary record is */
/* QE_BAM_FACTTBL */
&RSGRID = GetLevel0()(1).GetRowset(Scroll.QE_BAM_FACTTBL);


/* Get the rowset associated with Analytic grid whose primary record is */
/* QE_BAM_CCSMOKE */
&RSAGRID = GetLevel0()(1).GetRowset(Scroll.QE_BAM_CCSMOKE);

/* Flush out existing Data from the Analytic Grid */
&RSAGRID.Flush();

/* Copy data from Normal Grid to Analytic Grid in Freeze Column Mode*/
&RSGRID.CopyTo(&RSAGRID, Record.QE_BAM_FACTTBL, Record. QE_BAM_CCSMOKE);

Do not use the following methods with an analytic grid that is in Freeze Column Mode:

Analytic grid GetCubeCollection method
Analytic grid LoadData method
Analytic grid SetAnalyticInstance method
Analytic grid SetLayout method
Analytic grid SlicerVisible property

Error Handling

All the analytic type 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.

See Also

Try-Catch Sections

Data Types of the Analytic Grid Objects

Analytic grids are declared using the AnalyticGrid data type. For example,

Local AnalyticGrid &MyAnalyticGrid;

Analytic grid columns are declared using the AnalyticGridColumn data type. For example:

Local AnalyticGridColumn &MYGRIDCOL;

Scope of Analytic Grid Objects

Both the AnalyticGrid and AnalyticGridColumn objects can be instantiated from PeopleCode only.

An AnalyticGrid is a control on a page. You generally use these objects only in PeopleCode programs that are associated with an online process, not in an Application Engine program, a message notification, a Component Interface, and so on.

AnalyticGrid objects can be of scope local, component or global.

AnalyticGrid Class Reference

This reference for the AnalyticGrid class includes:

AnalyticGrid class built-in function.
AnalyticGrid class methods.
AnalyticGrid class properties.

AnalyticGrid Class Built-in Function

GetAnalyticGrid

AnalyticGrid Class Methods

In this section, we discuss the AnalyticGrid class methods. The methods are described in alphabetic order.

GetColumn

Syntax

GetColumn(ColumnName)

Description

Use the GetColumn method to instantiate an AnalyticGridColumn object.

Note. The properties for an AnalyticGridColumn and a GridColumn are the same. Any differences are indicated in the description for the GridColumn property.

Specify the grid column name in the page field properties for that field, consisting of any combination of uppercase letters, digits and "#", "$", "@", and "_".

To specify a grid column name:

Open the page in Application Designer, select the analytic grid and access the Analytic Grid control properties.
On the General tab, type the new grid name in Page Field Name.

Parameters

ColumnName

Specify the name of the column that you want to access.

Returns

An AnalyticGridColumn object.

Note. The properties for an AnalyticGridColumn and a GridColumn are the same. Any differences are indicated in the description for the GridColumn property.

See Also

GridColumn Class

GetCubeCollection

Syntax

GetCubeCollection()

Description

Use the GetCubeCollection method to return a reference to the cube collection associated with the analytic grid.

Note. Do not use this method with an analytic grid that is in Freeze Column Mode.

Parameters

None.

Returns

A CubeCollection object.

See Also

Analytic Calculation Engine Classes

CubeCollection Class

LoadData

Syntax

LoadData()

Description

Use the LoadData method to cause the system to get fresh data for the grid from the analytic calculation engine. Generally, you would use this method after you perform some operation, such as SetLayout, that might change the value or layout of the data.

Note. Do not use this method with an analytic grid that is in Freeze Column Mode.

Parameters

None.

Returns

None.

SetAnalyticInstance

Syntax

SetAnalyticInstance(ID)

Description

Use the SetAnalyticInstance method to specify the analytic instance to be associated with this analytic grid.

An AnalyticGrid object can be bound only once to an analytic instance. If the SetAnalyticInstance method is called after the analytic grid is bound to an instance, the method call has no effect.

Note. Do not use this method with an analytic grid that is in Freeze Column Mode.

Parameters

ID	Specify the analytic instance ID as a string.

Returns

None.

See Also

AnalyticInstance Class Methods

Analytic Calculation Engine Classes

SetLayout

Syntax

SetLayout(&SlicerArray, &RowAxisArray, &ColumnAxisArray)

Description

Use the SetLayout method to set the layout for the three axes, slice, row, and column.

Note. Do not use this method with an analytic grid that is in Freeze Column Mode.

If you specify No Drag drop mode for an analytic grid in Application Designer, the analytic grid has the column axis, row axis and slicer axis, but the end user isn't allowed to change the layout by dragging and dropping elements between axes. However, you can still change the layout using the SetLayout method.

Note. You can specify a null value ("") for all the required parameters for this method.

Parameters

&SlicerArray

Specify an already instantiated array of string containing the list of fields to be put on the slice axis.

&RowAxisArray

Specify an already instantiated array of string containing the list of fields to be put on the row axis.

&ColumnAxisArray

Specify an already instantiated array of string containing the list of fields to be put on the column axis.

Note. The maximum number of columns that can be displayed in an analytic grid is four.

Returns

None.

AnalyticGrid Class Properties

In this section we discuss the AnalyticGrid properties. The properties are described in alphabetic order.

Inactive

Description

Use this property to specify whether the analytic grid is inactive or active. This property takes a Boolean value, true if the grid is inactive, false otherwise.

If you specify this property as true, the analytic grid is not displayed to the user and no data is fetched from the database.

This property is read-write.

Label

Description

Use this property to specify the label that appears as the title of the grid.

Note. You can't use this property to set labels longer than 100 characters. If you try to set a label of more than 100 characters, the label is truncated to 100 characters. Always put any changes to labels in the Activate event for the page. This way the label is set every time the page is accessed.

This property is read-write.

ShowGridLines

Description

Use this property to specify whether grid lines are displayed with the analytic grid. This property takes a Boolean value, true to show the lines, false otherwise.

This property is read-write.

SlicerVisible

Description

Use this property to specify whether the slicer is displayed with the analytic grid. This property takes a Boolean value, true to show the slicer, false otherwise.

Note. Do not use this method with an analytic grid that is in Freeze Column Mode.

This property is read-write.

SummaryText

Description

Use this property to set or return a string representing the summary text for the analytic grid.

Summary text enables you to provide a brief description of the functionality and content of the grid area. This property is pertinent for users who access the application in accessibility mode using screen readers.

This property is read-write.

Example

&MyAnGrid = GetAnalyticGrid(Page.PSMYPAGE, "PSMYPAGE");
&MyAnGrid.SummaryText = "This is the new summary text through PeopleCode";

See Also

Setting Analytic Grid Label Properties