EnsPortal.MsgFilter.Assistant

class EnsPortal.MsgFilter.Assistant extends EnsPortal.MsgFilter.AbstractAssistant, Ens.Util.FunctionSet

Class to implement the server-side query construction and execution for the Message Viewer. Users may wish to extend this class to provide enhanced query generation for their particular application. If extended functionality is required, the name of the subclass should be specified in ^EnsPortal.Settings("MessageViewer","AssistantClass"). Users can override any of the methods in this class if they so choose, but specific APIs have been created to simplify functional changes. The addBasicConstraints()() can be overridden to specify particular handling for certain combinations of top-level Filter properties. The OnFinalizeSQL()()should be overridden is users only which to specify alternative JOIN orders in the FROM clause. (For an example of such syntax, see Ens.Enterprise.Portal.MsgFilter.Assistant.) Note: InterSystems is not responsible for user extensions to these classes.

Method Inventory

Parameters

parameter CONVERTTIMERANGES = 1;

Control whether range conditions (i.e. <, <=, >, >=) on the Header TimeCreated field should be converted to range conditions on the Header ID field instead.

parameter DOMAIN = Ensemble;

parameter IDCOL = ID;

Name of ID Column

parameter SESSIONSUBSCRIPT = MessageViewer;

Inherited description: Subscript under temporary session data to use for storing the search history for the viewer. The storage is activated by setting the ^Ens.Debug("UtilEnsMessages","sql") debug node to a positive number.

parameter TOPCOUNT = 10000000;

Number to use in SELECT TOP, if any. Use this to affect the SQL query optimizer. Set it substantially larger than MAXROWS if FilterRS() might invalidate some of the rows returned from SQL.

Properties

property BodyClasses [ MultiDimensional ];

Array to hold the encountered body classes.

Property methods: BodyClassesDisplayToLogical(), BodyClassesGet(), BodyClassesIsValid(), BodyClassesLogicalToDisplay(), BodyClassesLogicalToOdbc(), BodyClassesNormalize(), BodyClassesSet()

property NumSearchTabConds as %Integer [ MultiDimensional ];

Array to hold the number of SearchTable conditions.

Property methods: NumSearchTabCondsDisplayToLogical(), NumSearchTabCondsGet(), NumSearchTabCondsIsValid(), NumSearchTabCondsLogicalToDisplay(), NumSearchTabCondsNormalize(), NumSearchTabCondsSet()

property SearchTables [ MultiDimensional ];

Array to hold encountered SearchTables.

Property methods: SearchTablesDisplayToLogical(), SearchTablesGet(), SearchTablesIsValid(), SearchTablesLogicalToDisplay(), SearchTablesLogicalToOdbc(), SearchTablesNormalize(), SearchTablesSet()

property UseSTIN as %Boolean [ Transient ];

Flag to indicate whether an IN clause should be used when constructing SearchTable queries. The only situation where this should be False is when there is a single SearchTable equality condition -- in that case an IN clause is not required.

Property methods: UseSTINDisplayToLogical(), UseSTINGet(), UseSTINIsValid(), UseSTINLogicalToDisplay(), UseSTINNormalize(), UseSTINSet()

Methods

classmethod CreateFilter(pSearchCriteria As %ZEN.proxyObject, Output pFilter As EnsPortal.MsgFilter.Filter, pExcludeSequenceManager As %Boolean = 1, pVirtualKey As %Integer = 0) as %Status

Callback to create the Filter class for this Assistant. The paging logic is implemented in this method based on the nextPageStartId and nextPageEndId properties of the supplied proxyObject.

classmethod EnumerateClose(ByRef qHandle As %Binary) as %Status

Method to close off any references held by the query.

classmethod EnumerateExecute(ByRef qHandle As %Binary, Filter As EnsPortal.MsgFilter.Filter) as %Status

Initial method which parses the Filter into SQL terms and post-SQL terms. It then constructs an inner result set based on the SQL terms and calls the execute method of this inner result set.

classmethod EnumerateFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status

Method which actually implements fetching of data. Note that the postSQLFilter()() method of the Assistant is called to allow for any virtual document filters to be applied to the result set.

classmethod EnumerateGetInfo(colinfo As %List, parminfo As %List, idinfo As %List, qHandle As %Binary, extoption As %Integer = 0, extinfo As %List) as %Status

Callback to get metadata about the results from the inner resultset created in the EnumerateExecute() method. The metadata is created dynamically to reflect the columns present in the result set.

classmethod GetResultSet(pFilter As EnsPortal.MsgFilter.Filter, Output pResultSet As %ResultSet, pExecute As %Boolean = 1) as %Status

Helper method to return a valid ResultSet for the supplied Filter object. The result set construction itself is wrapped by the Enumerate query. The main goal is to branch the Sequence Manager the logic in this method, but subclasses can implement any logic they see fit to create a result set object.

classmethod GetSQLCondition(pOperator As %String, pProp As %String, pValue As %String, pDisplay As %Boolean = 0, pNoIndex As %Boolean = 0) as %String

Helper method to return a valid WHERE subclause condition for a supplied property reference (pProp), operator (pOperator) and value (pValue). The pDisplay flag controls whether the external display value is used for the value comparison. This is generally needed for properties of standard objects, as the display value may differ from the logical value.

method OnFinalizeSQL(Filter As EnsPortal.MsgFilter.Filter, ByRef pSelect As %String, ByRef pFrom As %String, ByRef pWhere As %String, ByRef pOrder As %String, ByRef pSelectTerms, ByRef pFromTerms) as %Status

Method to finalize the generated SQL query. Any modifications to JOIN order or the FROM clause should be implemented in this callback. The pSelect, pFrom, pWhere and pOrder arguments represent the SELECT, FROM, WHERE and ORDER BY clauses of the query thus far. The pSelectTerms and pFromTerms arguments are arrays that contain further values and tables which have yet to be added to the respective clauses. The contents of these arrays in combination with the state of the current Assistant can be used to determine what (if any) modifications should be made to the query as constructed by the parser.

classmethod SourceAndTargetEnumerateClose(ByRef qHandle As %Binary) as %Status

Method to release the references held by the query.

classmethod SourceAndTargetEnumerateExecute(ByRef qHandle As %Binary, Source As %String, Target As %String, Join As %String = "OR", TimeLen As %Integer = 999, StartId As %Integer = 0, EndId As %Integer = 0) as %Status

Method to initialise the retrieval of the data and create the query to retrieve information for a specific Message Header.

classmethod SourceAndTargetEnumerateFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) as %Status

Method which implements the retrieval for the query. The main goal here is to use the built-in SQL ability to order over the SourceConfigName and TargetConfigName bitmap indices in the reverse direction and then impose the AND or OR condition on the resulting ID values. The code may perform poorly for very large row counts, but given that this is for the UI, this should not be a problem.

method addBasicConstraints(Filter As EnsPortal.MsgFilter.Filter, ByRef where As %String = "", Output pTimeQuery As %Integer) as %Status

Callback to add constraints to the main query based on the top level conditions in the supplied Filter object. This method can be overridden in subclasses to apply more specific logic if needed.

method addHiddenColumn(pSchema As %String, pTable As %String, pColumnName As %String) as %Status

Helper method to hide the specified column when displaying the results of the generated SQL. pSchema specifies the schema name, pTable specifies the table name, and pColumnName specifies the name of the column to hide.

method addSQLTerms(ByRef aSelect, ByRef aFrom, Output xWhere, level=1, tNode="1", Output pAllowEmptyWhere As %Boolean, pBitmapIndexUsed As %Boolean = 0) as %Integer

Take from Terms tree whatever is best added to the SQL statement Return 0 means no SQL for node, 1 means node was partly done in SQL, 2 means node was completely accounted for in SQL pAllowEmptyWhere indicates that we are dealing with a display value, or a tree of display values.

classmethod addTerm(ByRef pArray, pTerm As %String = "", pNodeValue As %String = "")

method addTupleNodes(pSearchTableClass As %String, pTopNode As %String, ByRef pCondTree As %String)

Iterate over subnodes of the parse tree and add them to the tuple to be passed to the CustomSearchTable.

method getNodeCondition(pNode) as EnsPortal.MsgFilter.Condition

Single method to get the values from the parse tree into a Condition object.

method isHidden(pSchema As %String, pTable As %String, pColumnName As %String) as %Boolean

Helper method to determine whether a specific column in the SQL results should be displayed. pSchema specifies the schema name, pTable specifies the table name, and pColumnName specifies the name of the column to hide.

classmethod isTermComplete(ByRef pArray, pTerm As %String = "") as %Boolean

method parseTerms(pFilter As EnsPortal.MsgFilter.Filter) as %Status

Parse the list of filter terms and conditions into a local tree

method postSQLFilter(pFilter As EnsPortal.MsgFilter.Filter, pRS As %SQL.StatementResult, ByRef pPropVals, pLevel=1, pNode="1", pInOR=0) as %Boolean

Apply additional Filter criteria to determine whether to display the current row returned by the ResultSet. Return value 1 means display the current row. pPropVals is an array of calculated property values to extend the display list if the filter passes. The primary purpose of this filter is to allow for retrieval and matching of Virtual Document properties which are not indexed using SearchTables.

method processTuple(pNode As %String, pSearchTableClass As %String, pSQLTable As %String, pTableInFrom As %Boolean = 0, pSelectPrefix As %String = "SchTbl", ByRef pInitSelect As %String = "", ByRef pInitFrom As %String = "", ByRef pInitWhere As %String = "", ByRef pSqlFetch As %Boolean = 1)

Helper method to create a tuple tree that can be passed in to the OnProcessTuple() method of a CustomSearchTable class. The method first iterates over the parse tree to create the an abstraction that is then passed to OnProcessTuple(). This method is also responsible for processing the tree returned from OnProcessTuple() and pushing any updates back into the main parse tree.

method reduceTree()

Reduce Terms tree if possible by eliminating common terms

classmethod updateTerm(ByRef pArray, pTerm As %String = "", pNodeValue As %String = "")

Queries

query Enumerate(Filter As EnsPortal.MsgFilter.Filter)

Selects ID, TimeCreated, Session, Status, Error, Source, Target

List the messages matching the conditions in the supplied Filter. The actual logic for this query is implemented in the EnumerateExecute(), EnumerateFetch(), EnumerateClose() and EnumerateGetInfo() methods.

query SourceAndTargetEnumerate(Source As %String, Target As %String, Join As %String = "OR", TimeLen As %Integer = 999, StartId As %Integer = 0, EndId As %Integer = 0, GetBodyDetails As %Boolean = 0)

Selects ID, TimeCreated, Session, Status, Error, SourceConfigName, TargetConfigName

Custom query to retrieve data from the MessageHeader table when the results need to be displayed in Newest First sequence and the only other criteria are equality matches on the SourceConfigName and TargetConfigName fields where these two conditions can be combined using either an AND or and OR condition. The code implementing the query is in the SourceAndTargetEnumerateExecute(), SourceAndTargetEnumerateFetch() and SourceAndTargetEnumerateClose() methods.