Learning
Documentation
Community
Open Exchange
Global Masters
Home / Class Reference / ENSLIB namespace / %DeepSee.DataConnector
Private  Storage   

%DeepSee.DataConnector


abstract class %DeepSee.DataConnector extends
%CSP.Page, %RegisteredObject

Subclasses of this class are used to define DeepSee Data Connectors.
A DataConnnector provides a way to connect an input data source (such as the results of running an SQL query) to an output data sink (such as the dataSource for a DeepSee cube).
You can define the input data source by defining a SourceQuery XData block:

XData SourceQuery [ XMLNamespace = "http://www.intersystems.com/deepsee/connector/query" ]
{
<sql>
SELECT %ID,Product,AmountOfSale From MyApp.MyTable
</sql>
}
or, alternatively, you can implement the %OnGetSourceResultSet callback method. This method should create, prepare, and execute an %SQL.Statement and return the resulting ResultSet.
Method %OnGetSourceResultSet(ByRef pParameters, Output pResultSet) As %Status
{
	Set tSC = $$$OK
	Set pResultSet = ""
	Try {
		Set tStatement = ##class(%SQL.Statement).%New(,"DEFAULT_SCHEMA")
		Set tSC = tStatement.%Prepare("SELECT %ID,Product,AmountOfSale FROM MyApp.MyClass")
		If $$$ISERR(tSC) Quit
 		Set pResultSet = tStatement.%Execute()
	}
	Catch(ex) {
		Set tSC = ex.AsStatus()
	}
	Quit tSC
}
The output properties of the Data Connector are defined using the Output XData block. This contains an XML document that describes the set of output properties.
For example:
XData Output [ XMLNamespace = "http://www.intersystems.com/deepsee/connector/output" ]
{
<connector>
<property name="%ID" sourceProperty="ID" displayName="Record ID" />
<property name="Product" sourceProperty="Product" displayName="Product name"/>
<property name="AmountOfSale" sourceProperty="AmountOfSale" displayName="Amount of sale"/>
</connector>
}
A DataConnector is used by creating an instance of it and calling its %Execute method. This returns an instance of %SQL.StatementResult that can be used to read data from the DataConnector.
You can test a DataConnector class by calling its %Print method from the command line or you can view the DataConnector class as a web page.
If you are using a DataConnector class to supply data to a DeepSee cube the cube will take care of executing and fetching data from it.
A DataConnector can override the %OnNextRecord method if it wishes to perform additional logic on data flowing through the connector.
Each DataConnector class is also also a %CSP page; if you view it as a Web Page, you can view a test page for the DataConnector (you must hold Developer privileges to do this).

Inventory


Parameters Properties Methods Queries Indices ForeignKeys Triggers
3 7 24


Summary


Properties
%listingCube %listingKey %listingTable %singleId

Methods
%AddToSaveSet %ClassIsLatestVersion %ClassName %ConstructClone
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Execute
%Extends %GetConnectorInfo %GetKeyFields %GetParameter
%GetPropertyInfo %GetRestrictionClause %GetResultSetClass %GetSQLText
%IsA %IsModified %New %NormalizeObject
%ObjectModified %OnGetSourceResultSet %OnNextRecord %OnProcessRecord
%OnUpdateRecord %OriginalNamespace %PackageName %Print
%RemoveFromSaveSet %SerializeObject %SetIdList %SetMode
%SetModified %SetSingleId %SupportsIdList %SupportsSingleMode
%ToJSON %UpdateRecord %ValidateObject ConvertParameter
Decrypt Encrypt EscapeHTML EscapeURL
HyperEventCall HyperEventHead Include InsertHiddenField
InsertHiddenFields IsPrivate Link OnHTTPHeader
OnPage OnPageError OnPostHTTP OnPostHyperEvent
OnPreHTTP OnPreHyperEvent Page QuoteJS
RewriteURL ShowError StartTimer StopTimer
ThrowError UnescapeHTML UnescapeURL


Parameters


• parameter EXTERNALTABLE = 1;
Set this parameter TRUE (1) if this connector uses a linked (external) table. This is used to determine what form the id restriction used for listings ($$$RESTRICT token) should take. For external tables a more conservative approach, with a limit of 1000 records is used. If you know that your data source is based on a local table, you can set this parameter to 0 and more aggressive id restriction is used with no size limit,
• parameter SUPPORTSIDLIST = 0;
Set this parameter TRUE (1) if this connector supports "idlist" mode. The implementor is responsible for adding the additional query logic to support this mode.
• parameter SUPPORTSSINGLE = 0;
Set this parameter TRUE (1) if this connector supports "single" mode. The implementor is responsible for adding the additional query logic to support this mode.

Properties


• property %listingCube as %String;
If we are in "idlist" mode, this is the name of the cube asking for the listing.
• property %listingKey as %String;
If we are in "idlist" mode, this is the key value for the table containing the list of ids.
• property %listingTable as %String;
If we are in "idlist" mode, this is the name of the table containing the list of ids.
• property %singleId as %String;
Id of single record to fetch in "single" mode.

Methods


• method %Execute(ByRef pParameters, Output pSC As %Status) as %SQL.StatementResult
This executes the source result set and returns an instance of it to the consumer. This is used to fetch all data from this connector.
• final classmethod %GetConnectorInfo(Output pInfo As %List) as %Status
Return an array containing information about this connector. This takes the form:
pInfo = $LB(name,displayName)
• final classmethod %GetKeyFields(Output pKeys As %String) as %Status
Return an array containing information on the id key field(s) for this connector, if any. This takes the form:
pKeys(FieldName) = SourceField
This is used by utilities to discover information about this connector.
• final classmethod %GetPropertyInfo(Output pInfo As %List) as %Status
Return an array containing information on the properties of this connector. This takes the form:
pInfo(n) = $LB(name,displayName,type,idKey)
This is used by utilities to discover information about this connector.
• method %GetRestrictionClause(Output pClause As %String) as %Status
Return an SQL expression that tests the current idlist restrictions, if any. This expression can be used within an SQL WHERE statement. This is used to substitute any $$$RESTRICT values within a connector SQL statement.
• final classmethod %GetResultSetClass() as %String
Return the class name of the output result set associated with this connector.
• final classmethod %GetSQLText() as %String
Return the SQL statement defined by the SourceQuery XData block, if any.
• method %OnGetSourceResultSet(ByRef pParameters, Output pResultSet) as %Status
If implemented, this method is responsible for creating an instance of result set that will serve the data for this connector.
This method should test the current value of the %mode property. If %mode is "idlist", the query is responsible for restricting the set of records the ids in the listing table, %listingTable.
• method %OnNextRecord(ByRef pSC As %Library.Status = $$$OK) as %Library.Integer
This method is called by the output result set to fetch each record processed by this connector for cases where there is no source result set (if there is a source result set, this method is not called).
Returns 0 if there are no more records to fetch.
This method should fill in the properties of the %outputRecord object with the data that is to be returned.
• abstract method %OnProcessRecord(pRecord As %DeepSee.Connector.ResultSet, Output pSkip As %Boolean = 0) as %Status
If implemented, this method is called for each record processed by this connector before it is returned to the consumer.
pRecord is the current record.
pSkip, if true, indicates that this record should be skipped.
• classmethod %OnUpdateRecord(pID As %String, ByRef pValues, Output pMessage As %String) as %Status
Implement this method in order to update a particular record via the data connector.
• classmethod %Print(ByRef pParameters, pMaxRows As %Integer = 100) as %Status
Diagnostic method.
Create, execute, and display the data provided by this connector to the terminal.
pParameters is an array of parameters passed along to the %Execute method. pMaxRows, if not "", is the maximum number of records to display. The default is 100.
• method %SetIdList(pTableName As %String, pKey As %String, pCubeName As %String) as %Status
Set the name of the listing table and value of the key field that contains the list of ids to use in "idlist" mode.
A query of the form, SELECT _DSsourceId FROM *pTableName* WHERE _DSqueryKey = *pKey* will return the set of ids to use.
• method %SetMode(pMode As %String) as %Status
The operating mode of this connector.
Options are "all" (fetch all records), "idlist" (fetch records within a set of ids).
• method %SetSingleId(pID As %String) as %Status
Set the id of one record to fetch. The Connector must support id values. This is used to fetch one record for updating.
• method %SupportsIdList() as %Boolean
Test if this connector supports "idlist" mode.
• method %SupportsSingleMode() as %Boolean
Test if this connector supports "single" mode.
• classmethod %ToJSON(ByRef pParameters) as %Status
Write out all data in JSON format.
• final classmethod %UpdateRecord(pID As %String, ByRef pValues, Output pMessage As %String) as %Status
Update a particular record via the data connector. The actual work is done via the %UpdateRecord callback method, which is implemented within a subclass.
• classmethod OnPage() as %Status
Draw the test page.