Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [%DeepSee] >  [ResultSet]
Private  Storage   

class %DeepSee.ResultSet extends %ZEN.DataModel.DataModel

This class provides an API for executing queries against DeepSee cubes and viewing the results.
This class extends Zen data model so that it can efficiently work within the Zen MVC framework.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
25 67


Summary

Properties
%IsPlugIn %PlugInArguments %PlugInContextName %PlugInContextProp
%PlugInFilters %PlugInListingKey %Recompute %Statistics
%SubqueryResultSets %Trace %UseCache %id
%seriesCount %seriesNames listing listingFormatList
listingPage listingPageSize listingRows

Methods
%AddToSaveSet %CancelQuery %ClassIsLatestVersion %ClassName
%ClearStatistics %ConstructClone %CreateTable %DeleteModel
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Execute
%ExecuteAsynch %ExecuteAxes %ExecuteCells %ExecuteDirect
%ExecuteParameters %Extends %FormatNumber %GetAxisCount
%GetAxisMembers %GetAxisSize %GetCellCount %GetCellFormatOverride
%GetColumnCount %GetColumnTotal %GetCubeName %GetFiltersForCellRange
%GetGrandTotal %GetLastDataUpdate %GetLastSchemaUpdate %GetListingResultSet
%GetListingSQL %GetOrdinalKey %GetOrdinalLabel %GetOrdinalValue
%GetParameter %GetParameterInfo %GetPlan %GetPropertyInfo
%GetQuery %GetQueryKey %GetQueryStatus %GetQueryText
%GetRowCount %GetRowTotal %GetSlicerForCellRange %GetStatistic
%GetStatus %GetValue %HasCellFormatOverride %InvokeAction
%IsA %IsDrillThrough %IsModified %IsReadOnly
%New %NormalizeObject %ObjectModified %OnDeleteModel
%OnDeleteSource %OnGetPropertyInfo %OnInvokeAction %OnLoadModel
%OnNewSource %OnOpenSource %OnSaveSource %OnStoreModel
%OnSubmit %OpenModel %OriginalNamespace %PackageName
%ParseMDX %PrepareKey %PrepareMDX %PrepareObject
%Print %PrintListing %PrintStatistics %RemoveFromSaveSet
%RunQueryAuditCode %SaveModel %SerializeObject %SetListing
%SetModified %SetParameterContext %SetSubqueryResultset %ShowPlan
%SubmitHandler %UpdatePendingResults %ValidateObject


Properties

• property %IsPlugIn as %Integer [ InitialExpression = 0 ];
Indicates this is being run within the context of a plugin calculation.
• property %PlugInArguments as %ZEN.Datatype.string(XMLPROJECTION="NONE") [ MultiDimensional,Transient ];
Used in plugin concurrency protection
• property %PlugInContextName as %String;
Used in plugin concurrency protection
• property %PlugInContextProp as %String;
Used in plugin concurrency protection
• property %PlugInFilters as %ZEN.Datatype.string(XMLPROJECTION="NONE") [ MultiDimensional,Transient ];
Used in plugin concurrency protection
• property %PlugInListingKey as %String;
Used in plugin concurrency protection
• property %Recompute as %Boolean [ InitialExpression = 1 ];
If true recompute previously run queries whose data has been updated otherwise return old values.
• property %Statistics as %DeepSee.Datatype.string [ MultiDimensional ];
Array of timing and performance statistics for the current query.
• property %SubqueryResultSets as %DeepSee.ResultSet [ MultiDimensional ];
Container for the subquery resultsets of this execution.
• property %Trace as %Boolean [ InitialExpression = 0 ];
Debugging flag. If true write out tracing information to the console.
• property %UseCache as %Boolean [ InitialExpression = 1 ];
If true, then use results caching for this query.
• property listing as %String(MAXLEN=255);
If set, this is the name of a listing within the current cube to use for detail listings.
• property listingFormatList as %String(MAXLEN=5000);
Formatting string to apply to listing results.
• property listingPage as %Integer [ InitialExpression = 1 ];
Current "page" of listing query.
• property listingPageSize as %Integer [ InitialExpression = 1000 ];
Number of rows within a listing query "page".
• property listingRows as %Integer [ InitialExpression = 0 ];
Number of rows in the current listing query.

Methods

• classmethod %CancelQuery(pCubeName As %String, pQueryKey As %String) as %Status
Cancel the query, if running, specified by the cube name and query key.
• method %ClearStatistics()
Clear out current statistics for this result set.
• classmethod %CreateTable(pCubeName As %String = "", pNewTableName As %String = "", pContext As %String = "", pListingFields As %String = "", pListingName As %String = "") as %Status
Create an SQL table from DeepSee cube context. Arguments:
pCubeName (Required) - The name of the cube the new table should be generated from.
pNewTableName (Required) - The name of the table or class definition where the new result is to be stored. This must be a valid Schema.Table or Package.Class name, and the current user must have permission to create this class in the database to which it is mapped.
pContext (Optional) - An MDX restriction term which limits the results in the cube. While not required, this is strongly recommended since its ommission will result in the entire cube source being transferred to a table.
pListingFields (Optional) - A comma-delimited list of field names to be included in the new table. The field names must exist in the cube's source.
pListingName (Optional) - A named listing that is defined for use in the cube. This may be a native listing or a listing defined in a listing group. This will not be used if pListingFields is defined.

Most commonly this would be called from a KPI Action class. For example, an %OnDashboardAction callback might look like:
 ClassMethod %OnDashboardAction(pAction As %String, pContext As %ZEN.proxyObject) As %Status
 {
	Set tSC = $$$OK
	Try {
		Set tFilter = $P(pContext.currFilterSpec," ",2,*)
		Set tNewTableName = "Test.CreateResultTable"
		Set tListingFields = ""
		Set tListingName = "Listing"
		Set tSC = ##class(%DeepSee.ResultSet).%CreateTable(pContext.cubeName,tFilter,tNewTableName,tListingFields,tListingName) 
	}
	Catch ex {
		Set tSC = ex.AsStatus()
	}
	Quit tSC
 }
For simplicity this example hard codes the name of the new class definition, but this is not recommended in practice. The API will not replace any existing class, returning an error message instead. In order to allow the user to create their own class name, as well as provide the option to set values for tListingFields or tListingName, it is recommended the KPI action launch a popup dialog which manages the user's interaction with these settings and then calls the %CreateTable API.
• method %Execute(ByRef pParms) as %Status
Execute the current prepared query for this ResultSet.
If defined, pParms is an array of parameter values subscripted by parameter name (case-insensitive). These are supplied to the query and override the default values for any parameters defined by the query.
• method %ExecuteAsynch(Output pQueryKey As %String, ByRef pParms, pWait As %Boolean = 0, pAxesOnly As %Boolean = 0, pAxesQuery As %String = "") as %Status
Perform a complete execution of the ResultSet using background agents.
The query must be prepared before calling this method.
If defined, pParms is an array of parameter values subscripted by parameter name (case-insensitive). These are supplied to the query and override the default values for any parameters defined by the query.
If pWait is true, wait for the query to complete execution before returning.
If pAxesOnly is true, then only execute the axes for the query.
• method %ExecuteAxes() as %Status
Materialize the initial (pre-null-filtered) axes for this ResultSet.
• method %ExecuteCells() as %Status
Calculate the contents of the result cells for this Result Set.
• classmethod %ExecuteDirect(pMDX As %String, ByRef pParms, Output pSC As %Status) as %DeepSee.ResultSet
Convenience method.
Creates a result set, prepares the query pMDX, and executes it.
Returns an instance of the result set.
• method %ExecuteParameters(ByRef pParms) as %Status
Apply the array of parameter values to the currently prepared query.
• classmethod %FormatNumber(pValue As %Decimal, pFormat As %String, Output pType As %String, Output pStyle As %String) as %String
Apply MDX FORMAT_STRING pFormat to numeric value pValue.
• method %GetAxisCount(Output pInfo As %Integer) as %Integer
Return number of axes within the result set (not including the slicer). Returns 0 if the query has not been prepared and had its axes executed.
On return, pInfo will contain array of axis number (1-based) to axis top node number.
• method %GetAxisMembers(pAxis As %Integer, Output pKey, pItemNo As %Integer = "") as %Status
Get information on the members of a specific axis within the current query.
pAxis is the axis number (1 = cols, 2 = rows, etc.), 0 indicates that information for the slicer axis is to be returned.
Because it is impossible to pre-determine the size of a specific axis, the process private global, ^||DeepSee.AxisMembers is used to hold the results. The caller is responsible for killing this global.
On return, pKey contains the top-level subscript for the process private global under which the member information is stored.
The member information takes the form:
^||DeepSee.AxisMembers(pKey,pAxis,j,k) = $LB(nodeno,text,dimName,hierName,levelName,memberKey,dimNo,hierNo,levelNo,[aggregate])
pKey is the key returned by this method.
pAxis is the axis number.
j is the ordinal position of the tuple within the axis.
k is the ordinal position of the member within the tuple. k is 0 for members that form a stand-alone tuple. Otherwise k starts at 0 and increase towards the end of the tuple.
nodeno is the internal node number corresponding to the member within its axis.
text is the axis caption for the member.
Names are not enclosed within [ ] delimiters.
A fully-qualified name (UNAME) can be constructed by combining the names with the key:
Set tUName = "["_tDimName_"].["_tHierName_"].["_tLevelName_"].&["_tMemberKey_"]"
If pItemNo is provided, then it is the ordinal number of a single member within the axis and only information about this member is returned.
• method %GetAxisSize(pAxis As %Integer) as %Integer
Return number of visible nodes within the given axis (1-based).
• classmethod %GetCellCount(pCubeName As %String, pQueryKey As %String, Output pSC As %Status) as %Integer
Given a cube name and a query key (as returned by the %ExecuteAsync) return the number of result cells that are returned by the query.
• method %GetCellFormatOverride(pCell...) as %String
Determine if the format for the given cell has been overridden (such as by currentMember substitution) and return it. pCell... contains the ordinal address of the cell.
• method %GetColumnCount() as %Integer
Return the count of columns in results table.
• method %GetColumnTotal(pColumn As %Integer, pAgg As %String = "sum") as %String
Get the total associated with the given column (1-based).
• method %GetCubeName() as %String
Return the name of the cube this ResultSet is executing against. The result set must be prepared before calling this.
• method %GetFiltersForCellRange(Output pFilters As %String, pStartRow As %Integer, pStartCol As %Integer, pEndRow As %Integer, pEndCol As %Integer, Output pMeasure As %String, pAllRows As %Boolean = 0, pAllCols As %Boolean = 0, pSortCol As %Integer = 0, pSortDir As %String = "ASC", ByRef pPluginInfo As %String) as %Status
Find and return a an array of MDX %FILTER statements that will return the specified range of cells in the current query as a one-cell result.
On return, pFilters will contain the filter statement corresponding to each axis (1,2, etc) and the slicer (0).
For convenience, return the measure in play, if possible to determine.
• method %GetGrandTotal(pAgg As %String = "sum") as %String
Get the grand total for the current query.
This is a simple sum of all cells and not an "aggregate".
• method %GetLastDataUpdate() as %String
Output the cube last data update date in the XMLA format
• method %GetLastSchemaUpdate() as %String
Output the cube last schema update date in the XMLA format
• method %GetListingResultSet(Output pRS As %SQL.StatementResult, Output pFieldList As %List) as %Status
Prepare and execute the listing query for the current MDX statement. Return an SQL ResultSet that can be used to iterate over the listing. If pFieldList is not empty, then it is a $List of fields that should be selected and displayed from the result set.
• method %GetListingSQL() as %String
Return the SQL statement needed to drill into the source table for a DRILLTHROUGH statement. This may return the name of the DataConnector class if that is how the listing is defined.
• method %GetOrdinalKey(Output pKey As %String, pAxis As %Integer, pPosition As %Integer, Output pSpec) as %Integer
Find the axis key(s) for the item with ordinal position pPosition within axis pAxis (1 = cols, 2 = rows).
Returns, via pKey an array of labels associated with the item from the most specific to the most general.
If the item on the axis has no key (for example, measures), a placeholder "" is inserted into the pKey array to preserve the same structure as returned by %GetOrdinalLabel.
The return value is the number of keys returned.
• method %GetOrdinalLabel(Output pLabel As %String, pAxis As %Integer, pPosition As %Integer, Output pFormat As %String, Output pSolveOrder As %Integer, Output pStyle As %String, Output pHeaderStyle As %String, Output pClasses As %String, Output pTimeFormat As %String) as %Integer
Find the axis label(s) for the item with ordinal position pPosition within axis pAxis (1 = cols, 2 = rows).
Returns, via pLabel an array of labels associated with the item from the most specific to the most general.
The return value is the number of labels returned.
Also returns, by reference the format and solve order for the label (higher solve order takes precedence over lower and is used to determine which axis should supply the format for a cell). pClasses an array of classes associated with the item
• method %GetOrdinalValue(pCell...) as %String
Get the value of the cell specified by the ordinal cell numbers pCell1, pCell2...
A cell number is the ordinal number of a cell along its axis.
The column axis is axis number 1, the row axis is axis number 2 and so on.
If the result has more dimensions than are provided, or if values are omitted, then the first cell along each additional dimension is used.
• method %GetParameterInfo(Output pParms) as %Status
Return the set of named parameters values defined by the query.
• method %GetPlan(Output pPlan) as %Status
Utility method.
Assemble the query plan for this query. The query must have been successfully executed.
• method %GetQuery() as %DeepSee.Query.query
Return the DeepSee run-time query object currently in use as the source for this result set.
• method %GetQueryKey() as %String
Return the current Query Key for this Result Set. The result set must be prepared before calling this.
• classmethod %GetQueryStatus(pCubeName As %String, pQueryKey As %String, Output pPercentComplete As %Double, Output pSC As %Status, Output pPendingResults As %Boolean) as %Integer
Given a cube name and a query key (as returned by the %ExecuteAsync) return the current status of the query.
0 indicates that nothing has been done; 100 indicates that query execution is complete and that results are ready; a value in between means that work is ongoing.
• method %GetQueryText() as %String
Return the text of the query currently associated with this result set. This text is generated from the query parse tree and represents the canonic form of the query.
• method %GetRowCount() as %Integer
Return the count of rows in results table.
• method %GetRowTotal(pRow As %Integer, pAgg As %String = "sum") as %String
Get the total associated with the given row (1-based).
• method %GetSlicerForCellRange(Output pSlicer As %String, pStartRow As %Integer, pStartCol As %Integer, pEndRow As %Integer, pEndCol As %Integer, Output pMeasure As %String) as %Status
Find and return an MDX slicer statement that will return the specified range of cells in the current query as a one-cell result.
For convenience, return the measure in play, if possible to determine.
• method %GetStatistic(pStat As %String) as %String
Get the value of a specific query statistic. e.g. "ParseMDX".
For "query" stats, add "query." to the stat name: e.g. ""query.Slices".
• method %GetStatus(Output pPercentComplete As %Double, Output pSC As %Status, Output pPendingResults As %Boolean) as %Integer
Instance method version of %GetQueryStatus.
• method %GetValue(pNode...) as %String
Get the value of the cell specified by the node numbers pNode1, pNode2...
• method %HasCellFormatOverride() as %Boolean
Return true if the current query has to be tested for cell format overrides.
• method %IsDrillThrough() as %Boolean
Test if this is a DRILLTHROUGH statement.
• method %ParseMDX(pMDX As %String, pQuery As %DeepSee.Query.query) as %Status
Lower-level function that, given the text of a DeepSee MDX query, pMDX, parses it and converts it to a DeepSee run-time query object without changing the state of this Result Set.
• method %PrepareKey(pCubeName As %String = "", pQueryKey As %String = "", pPrepareMDX As %Boolean = 0) as %Status
Given a DeepSee query key, pQueryKey, (returned by a previous query prepare), restore the state of the query so that it can be executed.
• method %PrepareMDX(pMDX As %String, ByRef pVariables, Output pResolvedMDX) as %Status
Given the text of a DeepSee MDX query, pMDX, parse it, convert it to a DeepSee run-time query object, and prepare it so that it can then be executed.
pVariables is an optional list of pivot variable names and their current values. These are substituted for any pivot variable references within the query before it is parsed.
pResolvedMDX is the query text after any pivot variable references have been resolved.
• method %PrepareObject(pQuery As %DeepSee.Query.query, ByRef pVariables) as %Status
Given a DeepSee run-time query, pQuery, prepare it so that it can then be executed.
• method %Print(Output pStats, pShowNodeNo As %Boolean = 0, pMaxRows As %Integer = 0) as %Status
Utility method. Print the results of the current query to the console.
If pShowNodeNo is true, show the internal node numbers.
If pMaxRows is defined, limit the number of rows displayed.
• method %PrintListing()
Utility method.
For a DRILLTHROUGH query, print out the listing.
• method %PrintStatistics()
Write out current statistics for this result set.
• method %RunQueryAuditCode(pQuery As %DeepSee.Query.query) as %Status
Run the query audit code. (Test version).
This gives customer applications a chance to audit the queries run by DeepSee. This is called whenever a query is executed by %DeepSee.ResultSet.
The query audit code is a valid ObjectScript expression stored in the ^DeepSee.AuditQueryCode global. Audit query code should not write any output to the current device nor should this code kill any % variables required by Zen or DeepSee.
The variable, %dsQuery, will contain the text of the query.
• method %SetListing(pListing As %String) as %Status
Specify which listing to use for detail listings.
• method %SetParameterContext(ByRef pContext) as %Status
Take a pre-defined set of named parameters and apply them to MDX queries executed against this result set.
This makes it possible to add defined parameters to a query without adding them to the query text. This is different than supplying run-time values for parameters when executing the query.
The named parameter context is an array subscripted by UPPER CASE parameter name and parameter attribute (which can be "VALUE","TYPE",or "CAPTION").
For example:
pContext("CITY","VALUE") = "New York"
Call this before preparing a query.
• method %SetSubqueryResultset(pRS As %DeepSee.ResultSet = $$$NULLOREF, pStatus As %Status) as %Integer
Add a subquery resultset to the list of objects needed to complete this query. Returns zero if there was a failure to set the resultset into the list. Returns the index of the resutlset in the array when successful.
• method %ShowPlan()
Utility method.
Print out the plan for this query to the console. The query must have been successfully executed.
• method %UpdatePendingResults(Output pPending As %Boolean) as %Status
If the given query has pending results (such as from plug-ins), update them. Return if there are any additional pending results.


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.