Home > Class Reference > ENSLIB namespace > Ens.CustomSearchTable


abstract persistent class Ens.CustomSearchTable extends %Library.Persistent, Ens.SearchTableBase

SQL Table Name: Ens.CustomSearchTable

Base class for custom search tables that can implement alternative indexing strategies to those offered by the standard SearchTable structure. Note that this class does NOT support collection properties. Users wishing to create their own custom SearchTable must extend this class and can add any properties and indices they see fit. Users should consider which fields they wish to store on disk as properties of the CustomSearchTable, and which fields they want to retrieve at query time as "virtual" fields. See the documentation for GetPropertyList()() for more details regarding the behaviour of standard properties. If any virtual fields are desired, then the GetVirtualPropertyList()() and GetVirtualProperty()() methods need to be overridden to list and retrieve named virtual properties, respectively. Note that the default approach for querying on non-indexed fields is to display them in the query results without applying any conditions to the values. However, users may choose to modify the generated SQL clauses for each condition by overriding the OnProcessCondition()() method to implement more complex logic. Irrespective of any other decisions, the user MUST override the OnIndexDoc()() method, which populates the CustomSearchTable object.

For even more control over the generated SQL, users can override the PROCESSTUPLES parameter to ensure that the OnProcessTuple()() callback is invoked during query generation. The OnProcessTuple()() callback gives users a tree of related conditions for a given SearchTable so that users can generate custom SQL conditions for groups of conditions, rather than the per-property approach available via the OnProcessCondition()() callback. See the documentation for OnProcessTuple() to get more details about this tree-based approach.

Property Inventory

Method Inventory


parameter PROCESSTUPLES = 0;
Flag to indicate whether the OnProcessTuple()() callback should be invoked for the SearchTable when generating SQL in the viewer. The flag is used in the base implementation of ProcessTuples(), which is the definitive method used by the Assistant classes, to determine whether OnProcessTuple() should be called.


property DocId as %String (COLLATION = "EXACT") [ Required ];
The ID of the document / message body object this row is associated with.
Property methods: DocIdCheck(), DocIdDelete(), DocIdDisplayToLogical(), DocIdExists(), DocIdGet(), DocIdIsValid(), DocIdLogicalToDisplay(), DocIdLogicalToOdbc(), DocIdNormalize(), DocIdOpen(), DocIdSQLCheckUnique(), DocIdSQLExists(), DocIdSQLFindPKeyByConstraint(), DocIdSQLFindRowIDByConstraint(), DocIdSet()


classmethod CheckFilter(pFilter As EnsPortal.MsgFilter.Filter, pWarnings As %Library.ListOfDataTypes) as %Status

Helper method to allow developers to inform users about possibly problematic search criteria. If the current custom search table has been specified in any criteria, then this method will be called once by the UI. If the requested search may be slow, then the developer can append any number of message strings to pWarnings. If any strings are returned, all the returned strings will be displayed to the user, and the user can make a decision as to whether he or she wishes to continue with the search as constructed.

Note: this method is called before we attempt to generate any SQL to ensure that the user gets close to immediate feedback on his/her search.

classmethod GetPropertyList(Output pIndexedProperties As %List, Output pProperties As %List) as %Status

Method to list the properties and indexed properties of a given CustomSearchTable. By default, this is code generated, but this method may be overridden in subclasses to implement different behaviour. Both output variables should return a Caché list of properties. pIndexedProperties should contain a list of indexed properties available in the CustomSearchTable, and pProperties should contain a list of available properties in the CustomSearchTable. The distinction is to allow the UI to list indexed properties before non-indexed properties.

Note that virtual properties are also supported, but should be listed using GetVirtualPropertyList()(). Such a construct permits the retrieval of arbitrary data from the database either by constructing custom SQL for the term based on the value, or by invoking a callback function after the initial SQL results have been produced.

classmethod GetVirtualProperties(pDocID As %String, pPropNames As %List, Output pPropValues As %List) as %Status
API to retrieve a named list of virtual properties. The base implementation of this method is a thin wrapper around GetVirtualProperty()(), but users can override this method in situations where common work can be accomplished before attempting to retrieve multiple values. Note that the positional order of the values in pPropNames and pPropValues should be kept the same.
classmethod GetVirtualProperty(pDocID As %String, pPropName As %String, Output pPropValue As %String, ByRef pUserArgs) as %Status
API to retrieve a named virtual property for a given document ID. If a virtual property is specified in GetVirtualPropertyList()(), this method should be updated to implement retrieval code for the property. Note that if GetVirtualProperties()() is overridden, this method may not be called for value retrieval.
classmethod GetVirtualPropertyList(Output pIndexedVirtualProperties As %List, Output pVirtualProperties As %List) as %Status
Helper method to specify "virtual" properties for a custom searchtable.
final classmethod GetVirtualPropertyProc(pClassname As %String, pDocID As %String, pPropName As %String) as %String [ SQLProc = CustomSearchTable_GetVirtualPropertyProc ]
Stored Procedure to retrieve the value of a named virtual property for a specified class and ID. This exposes GetVirtualProperty()() to SQL operations so virtual properties can be retrieved directly from SQL queries in the viewer pages.
final classmethod IndexDoc(pDocObj As %Persistent) as %Status
Implementation of the IndexDoc method. User code must override the OnIndexDoc()() callback.
classmethod IsIndexedProperty(pPropertyName As %String = "") as %Boolean
Helper method to indicate whether a property is indexed.
classmethod IsVirtualProperty(pPropertyName As %String = "") as %Boolean
Helper method to indicate whether a property is a virtual property.
classmethod ListAllProperties(Output pIndexedProperties As %List, Output pProperties As %List) as %Status
Helper method used by the portal UI to determine which fields are available for the SearchTable. The default implementation relies on GetPropertyList()() and GetVirtualPropertyList()() to get the full list of available properties. Users may override this implementation in subclasses, but it would be better to override the methods mentioned above where necessary.
classmethod OnIndexDoc(pDocObj As %Persistent, pSearchTable As Ens.CustomSearchTable) as %Status
Callback which MUST be implemented by users to populate the CustomSearchTable supplied in pSearchTable based on the source object in pDocObj. Note that the DocId property is prepopulated, so doesn't need to be reset. If the user doesn't want a particular CustomSearchTable instance to be saved, the user can set pSearchTable to the empty string (i.e. "") to prevent the indexing framework from saving an entry to disk.
classmethod OnProcessCondition(pProperty As %String, pOperator As %String, pValue As %String, pTableName As %String, pTableInFrom As %Boolean, pSelectAsName As %String, pDisplayOnly As %Boolean = 0, ByRef pSelect As %String, ByRef pFrom As %String, ByRef pWhere As %String, ByRef pSQLFetch As %Boolean) as %Status

Callback invoked by the Message Viewer UI whenever a condition for a CustomSearchTable is selected AND the condition has not been marked as complete by the OnProcessTuple()() callback. The arguments for the method are as follows:

  • pProperty specifies the property name to be retrieved.
    Note: pProperty may be the empty string when adding a SearchTable for the first time. Ensure that the code in this method handles this case.
  • pDisplayOnly indicates whether the user has selected the property as a display-only field. If pDisplayOnly is true, the values for the value and operator supplied in pValue and pOperator, respectively, should be ignored and no conditions should be added to the WHERE clause. If pDisplayOnly is false, users should make use of the GetSQLCondition() API in EnsPortal.MsgFilter.Assistant to produce valid SQL WHERE conditions based on th