%DeepSee.ResultSet

Class %DeepSee.ResultSet Extends %ZEN.DataModel.DataModel [ System = 4 ]

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.

Properties

%Trace

Property %Trace As %Boolean [ InitialExpression = 0 ];

Debugging flag. If true write out tracing information to the console.

%Query

Property %Query As %DeepSee.Query.query [ Internal ];

Run-time query object that will serve as the source for this result set.

%Cube

Property %Cube As %DeepSee.Datatype.string [ Internal ];

Name of the cube this query is based on.

%CubeKey

Property %CubeKey As %DeepSee.Datatype.string [ Internal ];

Canonic (index) name of the cube this query is based on.

%QueryKey

Property %QueryKey As %DeepSee.Datatype.string [ Internal ];

Query key for the current query.

%Statistics

Property %Statistics As %DeepSee.Datatype.string [ MultiDimensional ];

Array of timing and performance statistics for the current query.

%UseCache

Property %UseCache As %Boolean [ InitialExpression = 1 ];

If true, then use results caching for this query.

%Recompute

Property %Recompute As %Boolean [ InitialExpression = 1 ];

If true recompute previously run queries whose data has been updated otherwise return old values.

%AxisCount

Property %AxisCount As %Integer [ Internal ];

Holds the number of axes in the current query.

%NamedParameters

Property %NamedParameters As %Integer [ Internal, MultiDimensional ];

Array of named parameters with current values. These are set by the %SetParameterContext method.

%ListingSQL

Property %ListingSQL As %String(MAXLEN = 32000) [ Private ];

This holds the SQL query generated by a DRILLTHROUGH query. Use the %GetListingSQL to get this.

%ListingResult

Property %ListingResult As %SQL.StatementResult [ Private ];

This holds the SQL StatementResult object created by a DRILLTHROUGH query. Use the %GetListingResult to get this.

%ListingFields

Property %ListingFields As %List [ Private ];

List of fields to display for a DRILLTHROUGH query. Use the %GetListingResult to get this.

%IsPlugIn

Property %IsPlugIn As %Integer [ InitialExpression = 0 ];

Indicates this is being run within the context of a plugin calculation.

%PlugInListingKey

Property %PlugInListingKey As %String;

Used in plugin concurrency protection

%PlugInContextName

Property %PlugInContextName As %String;

Used in plugin concurrency protection

%PlugInContextProp

Property %PlugInContextProp As %String;

Used in plugin concurrency protection

%PlugInFilters

Property %PlugInFilters As %ZEN.Datatype.string(XMLPROJECTION = "NONE") [ MultiDimensional, Transient ];

Used in plugin concurrency protection

%PlugInArguments

Property %PlugInArguments As %ZEN.Datatype.string(XMLPROJECTION = "NONE") [ MultiDimensional, Transient ];

Used in plugin concurrency protection

listing

Property listing As %String(MAXLEN = 255);

If set, this is the name of a listing within the current cube to use for detail listings.

listingRows

Property listingRows As %Integer [ InitialExpression = 0 ];

Number of rows in the current listing query.

listingPageSize

Property listingPageSize As %Integer [ InitialExpression = 1000 ];

Number of rows within a listing query "page".

listingPage

Property listingPage As %Integer [ InitialExpression = 1 ];

Current "page" of listing query.

listingFormatList

Property listingFormatList As %String(MAXLEN = 5000);

Formatting string to apply to listing results.

%LockKeys

Property %LockKeys As %String [ MultiDimensional ];

Store the keys of any locks taken out by this query.

%AncestorLockKeys

Property %AncestorLockKeys As %String [ MultiDimensional ];

Store the keys of any locks taken out by ancestors of this query in a lookup index. The presence of locks in this index will mean the locks are already protected at the time of execution for this ResultSet.

%LockMode

Property %LockMode As %String [ InitialExpression = "exclusive" ];

Lock mode determines whether this resultset is operating in read or write mode. Do not change this property directly - use %SetLockMode.

%LocksEngaged

Property %LocksEngaged As %Boolean [ InitialExpression = 0 ];

Current state of the resultset locks.

%UseLocal

Property %UseLocal As %Boolean [ InitialExpression = 0 ];

If true, a private copy of the resultset is available.

%ResultCacheLocation

Property %ResultCacheLocation As %String [ InitialExpression = {$Name($$$DeepSeeResultsGLVN)} ];

This points to the global location that has the results portion of the resultset.

%AxisCacheLocation

Property %AxisCacheLocation As %String [ InitialExpression = {$Name($$$DeepSeeAxisGLVN)} ];

This points to the global location that has the axis portion of the resultset.

%SessionKey

Property %SessionKey As %String [ InitialExpression = {$I($$$DeepSeeLocalResultsGLVN("session"))} ];

A unique session key for the current resultset.

%SubqueryResultSets

Property %SubqueryResultSets As %DeepSee.ResultSet [ MultiDimensional ];

Container for the subquery resultsets of this execution.

%KeepLocalResults

Property %KeepLocalResults As %Boolean [ InitialExpression = 0 ];

If true, the private copy of the resultset will not be deleted after the resultset is closed

Methods

%ExecuteDirect

ClassMethod %ExecuteDirect(pMDX As %String, ByRef pParms, Output pSC As %Status, pAsync = 0, pWait = 1) As %DeepSee.ResultSet

Convenience method.
Creates a result set, prepares the query pMDX, and executes it.
Returns an instance of the result set.

%PrepareMDX

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.

%PrepareObject

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.

%PrepareKey

Method %PrepareKey(pCubeName As %String = "", pQueryKey As %String = "", ByRef pParms, pOriginalMDX As %String = "") 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.

%SetListing

Method %SetListing(pListing As %String) As %Status

Specify which listing to use for detail listings.

%SetParameterContext

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.

%GetQuery

Method %GetQuery() As %DeepSee.Query.query

Return the DeepSee run-time query object currently in use as the source for this result set.

%GetQueryKey

Method %GetQueryKey() As %String

Return the current Query Key for this Result Set. The result set must be prepared before calling this.

%GetCubeName

Method %GetCubeName() As %String

Return the name of the cube this ResultSet is executing against. The result set must be prepared before calling this.

%GetLastDataUpdate

Method %GetLastDataUpdate() As %String

Output the cube last data update date in the XMLA format

%GetLastSchemaUpdate

Method %GetLastSchemaUpdate() As %String

Output the cube last schema update date in the XMLA format

%GetListingResultSet

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.

%GetListingSQL

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.

%IsDrillThrough

Method %IsDrillThrough() As %Boolean

Test if this is a DRILLTHROUGH statement.

%GetQueryText

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.

%GetQueryStatus

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.

%GetCellCount

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

%CancelQuery

ClassMethod %CancelQuery(pCubeName As %String, pQueryKey As %String) As %Status

Cancel the query, if running, specified by the cube name and query key.

%GetStatus

Method %GetStatus(Output pPercentComplete As %Double, Output pSC As %Status, Output pPendingResults As %Boolean) As %Integer

Instance method version of %GetQueryStatus.

%GetParameterInfo

Method %GetParameterInfo(Output pParms) As %Status

Return the set of named parameters values defined by the query.

%Execute

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.

%ExecuteAsynch

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.

%ExecuteParameters

Method %ExecuteParameters(ByRef pParms) As %Status

Apply the array of parameter values to the currently prepared query.

%ExecuteAxes

Method %ExecuteAxes() As %Status

Materialize the initial (pre-null-filtered) axes for this ResultSet.

%ExecuteCells

Method %ExecuteCells() As %Status

Calculate the contents of the result cells for this Result Set.

%ExecuteListing

Method %ExecuteListing(pStoreFactBits As %Boolean = 0) As %Status [ Internal ]

For a DRILLTHROUGH query, find the set of source ids that make up the *first* cell in the results and compute the SQL statement needed to fetch the request fields from the source table (either as specified in the query's RETURN clause or the default listing for the cube).

RewriteQueryTag

ClassMethod RewriteQueryTag(ByRef pSQL As %String, pTagName As %String, pRewrite As %String, pDefaultParams As %List = "", pDefaultAlias As %String = "", pAliasPrefix As %String = "", pStatic As %Boolean = 0) As %Status [ Internal ]

Replaces a "tag" in a listing query pSQL (fieldList or straight SQL), using the string in pRewrite. The tag (such as $$$IKSUMMARY) can have zero or more parameters in square brackets, which will be used to replace $$$1, $$$2, etc markers in pRewrite, defaulting to the corresponding positions in pDefaultParams if no value is supplied with the tag. pRewrite is supposed to contain appropriate quotes, as surrounding single and double quotes in the tag itself will be removed. If pDefaultAlias is non-null, it will be appended as the column alias for the rewrite expression. This alias can also contain $$$1, $$$2, etc markers. If pAliasPrefix is set, it will be prepended to any existing (or default) alias. If pStatic=1, the rewrite code is considered to be COS code and run once, with its result then replacing the tag in the query.

%ExecuteSessionCommand

Method %ExecuteSessionCommand() As %Status [ Internal, Private ]

Perform the work of a CREATE or DROP statement.

%GetAxisSize

Method %GetAxisSize(pAxis As %Integer) As %Integer

Return number of visible nodes within the given axis (1-based).

%GetColumnCount

Method %GetColumnCount() As %Integer

Return the count of columns in results table.

%GetRowCount

Method %GetRowCount() As %Integer

Return the count of rows in results table.

%GetAxisCount

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.

%HasCellFormatOverride

Method %HasCellFormatOverride() As %Boolean

Return true if the current query has to be tested for cell format overrides.

%GetCellFormatOverride

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.

%GetOrdinalValue

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.

%GetValue

Method %GetValue(pNode...) As %String

Get the value of the cell specified by the node numbers pNode1, pNode2...

%GetOrdinalLabel

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

%GetOrdinalLabelNodes

Method %GetOrdinalLabelNodes(pAxis As %Integer, pPosition As %Integer, ByRef pNodeArray) As %Status [ Internal ]

Examine the axis nodes(s) for the item with ordinal position pPosition within axis pAxis, and build an array of nodes contributing to the label at this ordinal position along the axis. The collection of nodes is returned in the format
pNodeArray(nodeNumber) = $LB(nodeInfo).

%GetOrdinalKey

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.

%GetRowTotal

Method %GetRowTotal(pRow As %Integer, pAgg As %String = "sum") As %String

Get the total associated with the given row (1-based).

%GetColumnTotal

Method %GetColumnTotal(pColumn As %Integer, pAgg As %String = "sum") As %String

Get the total associated with the given column (1-based).

%GetGrandTotal

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

%GetPlan

Method %GetPlan(Output pPlan) As %Status

Utility method.
Assemble the query plan for this query. The query must have been successfully executed.

%GetPlanForQuery

Method %GetPlanForQuery(ByRef pPlan, pCubeName As %String, pQueryKey As %String, pLevel As %Integer = 0) [ Internal, Private ]

Show plan details for the given query. Do not call this directly.

%ShowPlan

Method %ShowPlan()

Utility method.
Print out the plan for this query to the console. The query must have been successfully executed.

%ShowPlanForQuery

Method %ShowPlanForQuery(pCubeName As %String, pQueryKey As %String, pLevel As %Integer = 0) [ Internal, Private ]

Show plan details for the given query.

%Print

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.

%PrintListing

Method %PrintListing()

Utility method.
For a DRILLTHROUGH query, print out the listing.

%ParseMDX

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.

%GetAxisMembers

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.

%ClearStatistics

Method %ClearStatistics()

Clear out current statistics for this result set.

%GetStatistic

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

%PrintStatistics

Method %PrintStatistics()

Write out current statistics for this result set.

%FormatNumber

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.

%CopyDataFromModel

Method %CopyDataFromModel(Output pData, Output pTypes, pSeries As %Integer = "") As %Status [ Internal ]

Internal method.
Local implementation of DataModel API.

%GetModelInfo

Method %GetModelInfo(Output pPropNames As %String, Output pPropTypes As %Integer, Output pPropLabels As %String) As %Status [ Internal ]

Internal method.
Called by controller to get meta data for the current query. Each metadata value is a csv list.

%GetSlicerForCellRange

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.

%TestFilters

ClassMethod %TestFilters(pMDX As %String) As %Status [ Internal ]

Test for %GetFiltersForCellRange.

%GetFiltersForCellRange

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. For cell ranges with multiple measures, the measure applied to the cell pStartRow, pStartCol is returned.

%GetCellMetric

Method %GetCellMetric(pRow As %Integer = 1, pCol As %Integer = 1, pSC As %Status = {$$$OK}) As %String

Provided a (row,col) cell address within this resultset, determine which measure is being applied.

%OutputXMLA

Method %OutputXMLA() As %Status [ Internal ]

Output the result of the current query in XML/A format to the current device. The query should be prepared and executed first.
If there is an error, it is assumed that the caller will transform the status value into a SOAP fault.

%GetDefaultFormat

Method %GetDefaultFormat(Output pCaption As %String) As %String [ Internal ]

Return the default format string for this result. Also returns the default label (measure name).

%OutputJSON

Method %OutputJSON(pPageSize As %Integer, pCurrPage As %Integer, pRowLabels As %List = "", pMaxRows As %Integer = "") As %Status [ Internal ]

Output the result of the current query in XML/A format to the current device. The query should be prepared and executed first.
If there is an error, it is assumed that the caller will transform the status value into a SOAP fault.

%UpdatePendingResults

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.

%RunQueryAuditCode

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.

%CreateTable

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, tNewTableName, tFilter, 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.

%SetSubqueryResultset

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.

%InitializeResultSet

Method %InitializeResultSet() As %Status

Initialize this resultset to ready it for executing a new query. This may be called on a newly instantiated ResultSet or on a ResultSet that has already been used to execute a different MDX query.

%SetLockKeys

Method %SetLockKeys(pRefreshKeys = 0, pWait = 0) As %Status

Fill the %LockKeys array for the current query. This will only succeed if the query has been prepared. Keys will be prepended with either "results" or "axis" to indicate whether the particular key applies to the Results cache or the Axis cache, respectively. This does not do the actual work of acquiring locks.
Once the locks are determined they are immediately copied to the current %Query object using %CopyLockKeysToQuery. The value of the pWait flag is passed through to this method to maintain proper tracking of the lock hierarchy.

%SetAncestorLockKeys

Method %SetAncestorLockKeys(ByRef pAncestorLocks) As %Status

Fill the %AncestorLockKeys array for the current ResultSet using the named lock keys defined in pAncestorLocks. This method will support a key set supplied as a comma-delimited string, a $LB, or a COS array.
When taking out locks in %AcquireLocks it will be assumed any locks present in this array are held by a waiting parent process and so these particular locks will be exempted.

%ClearLockKeys

Method %ClearLockKeys(pLockMode As %String = "") As %Status

Clear up the locks held by the process and reset the local state variables. If pLockMode is supplied, use it to set the ResultSet's %LockMode.

%CopyLockKeysToQuery

Method %CopyLockKeysToQuery(pWait = 0) As %Status

This method copies the current ResultSet's lock keys into the active query to make the references available for subqeries and tasks. If pWait is set, this communicates the current ResultSet intends to wait for results and will maintain a hold on the locks securing the current resources.

%AcquireLocks

Method %AcquireLocks(pStatus As %Status = {$$$OK}, pLockMode As %String = {..%LockMode}, pTimeout = -1) As %Boolean

Acquire locks needed to secure access to the shared result and axes caches for this query. The parameter pLockMode controls which type of locks (exclusive/shared) should be attempted, by default this will be the ResultSet's current %LockMode setting. This method returns either
0 - The method was unable to acquire all of the locks associated with this query
1 - The method has successfully acquired all locks needed to safely interact with the shared cache
In the event a "0" is returned, any and all locks acquired by this process are released.
Optionally the pTimeout parameter may be supplied to instruct this method to wait for a successful lock on the group of lock keys as a whole. The method will return 1 if all locks are obtained before the requested timeout and 0 otherwise. Optional values for this parameter are:
-1 [default] - Make one attempt at obtaining the group of locks and return the result.
0 - Wait indefinitely for all locks in the %LockKeys group to be successfully obtained.
(positive number) - Wait up to the specified amount of time and return the success status for the %LockKeys group.

%ReleaseLocks

Method %ReleaseLocks(pLockMode As %String = {..%LockMode}) As %Status

Release all locks of the type pLockMode held by this ResultSet.

%SetLockMode

Method %SetLockMode(pType = "exclusive") As %Status

Accessor method for changing the %LockMode of this ResultSet. This is protected from changing the mode when locks are engaged.

%SwitchToLocalCache

Method %SwitchToLocalCache() As %Status

Create a local copy of the shared Results and Axis caches and reconfigure the location pointers to the private cache data.

%SwitchToCommonCache

Method %SwitchToCommonCache() As %Status

This method returns the pointers to uing the common cache.

%SetLocationLocal

Method %SetLocationLocal() As %Status

Look at local cache for reading data

%SetLocationCommon

Method %SetLocationCommon() As %Status

Look at common cache for reading data

%CopyResultToLocal

Method %CopyResultToLocal() As %Status

This does the actual work of copying results from the shared caches to a local copy unique to this ResultSet's %SessionKey. This operation can only be performed if the ResultSet has locks engaged.

%ClearLocalResult

Method %ClearLocalResult() As %Status

Perform the actual work of deleting the local copies of the Results and Axis caches.

%OnClose

Method %OnClose() As %Status [ Private, ServerOnly = 1 ]

This callback method is invoked by the %Close method to provide notification that the current object is being closed.

The return value of this method is ignored.