%DeepSee.DataConnector

abstract class %DeepSee.DataConnector extends %CSP.Page, %Library.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).

Method Inventory

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 methods: %listingCubeDisplayToLogical(), %listingCubeGet(), %listingCubeIsValid(), %listingCubeLogicalToDisplay(), %listingCubeLogicalToOdbc(), %listingCubeNormalize(), %listingCubeSet()

property %listingKey as %String;

If we are in "idlist" mode, this is the key value for the table containing the list of ids.

Property methods: %listingKeyDisplayToLogical(), %listingKeyGet(), %listingKeyIsValid(), %listingKeyLogicalToDisplay(), %listingKeyLogicalToOdbc(), %listingKeyNormalize(), %listingKeySet()

property %listingTable as %String;

If we are in "idlist" mode, this is the name of the table containing the list of ids.

Property methods: %listingTableDisplayToLogical(), %listingTableGet(), %listingTableIsValid(), %listingTableLogicalToDisplay(), %listingTableLogicalToOdbc(), %listingTableNormalize(), %listingTableSet()

property %singleId as %String;

Id of single record to fetch in "single" mode.

Property methods: %singleIdDisplayToLogical(), %singleIdGet(), %singleIdIsValid(), %singleIdLogicalToDisplay(), %singleIdLogicalToOdbc(), %singleIdNormalize(), %singleIdSet()

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.