%DeepSee.DataConnector

Class %DeepSee.DataConnector Extends (%CSP.Page, %RegisteredObject) [ Abstract, System = 4 ]

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" ] { SELECT %ID,Product,AmountOfSale From MyApp.MyTable } 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" ] { } 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).

Parameters

SUPPORTSIDLIST

Parameter SUPPORTSIDLIST As BOOL = 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.

SUPPORTSSINGLE

Parameter SUPPORTSSINGLE As BOOL = 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.

EXTERNALTABLE

Parameter EXTERNALTABLE As BOOL = 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,

Properties

%parameters

Property %parameters [ Internal, MultiDimensional ];

This is used to pass input parameters to the generated result set.

%outputRecord

Property %outputRecord As %SQL.IResultSet [ Private ];

Output Result Set object that emits the records to the consumer. This is created by the %Execute method.

%mode

Property %mode As %String [ InitialExpression = "all", Internal ];

Specify what mode this data connector is in.
Options are "all" (fetch all records), "idlist" (fetch record within a given set of ids), or "single" (fetch one record specified by %singleId).

%listingCube

Property %listingCube As %String;

If we are in "idlist" mode, this is the name of the cube asking for the listing.

%listingTable

Property %listingTable As %String;

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

%listingKey

Property %listingKey As %String;

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

%singleId

Property %singleId As %String;

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

XDatas

SourceQuery

XData SourceQuery [ XMLNamespace = "http://www.intersystems.com/deepsee/connector/query" ]

This optional XData definition defines the sql query used to supply data to this data connector.
The columns selected by this query should match the sourceProperty names in this connector's Output definition.

Output

XData Output [ XMLNamespace = "http://www.intersystems.com/deepsee/connector/output" ]

This XData definition defines the DataConnector output specification.

Methods

%SupportsIdList

Method %SupportsIdList() As %Boolean

Test if this connector supports "idlist" mode.

%SupportsSingleMode

Method %SupportsSingleMode() As %Boolean

Test if this connector supports "single" mode.

%SetMode

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

%SetIdList

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.

%SetSingleId

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.

%Execute

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.

%GetSourceResultSet

Method %GetSourceResultSet(ByRef pParameters, Output pResultSet) As %Status [ Final, Internal ]

Return the source result set that provides the data for this connector.

%OnGetSourceResultSet

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.

%OnNextRecord

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.

%OnProcessRecord

Method %OnProcessRecord(pRecord As %DeepSee.Connector.ResultSet, Output pSkip As %Boolean = 0) As %Status [ Abstract ]

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.

%UpdateRecord

ClassMethod %UpdateRecord(pID As %String, ByRef pValues, Output pMessage As %String) As %Status [ Final ]

Update a particular record via the data connector. The actual work is done via the %UpdateRecord callback method, which is implemented within a subclass.

%OnUpdateRecord

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.

%GetResultSetClass

ClassMethod %GetResultSetClass() As %String [ CodeMode = objectgenerator, Final ]

Return the class name of the output result set associated with this connector.

%GetConnectorInfo

ClassMethod %GetConnectorInfo(Output pInfo As %List) As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %GenerateConnector ]

Return an array containing information about this connector. This takes the form:
pInfo = $LB(name,displayName)

%GetSQLText

ClassMethod %GetSQLText() As %String [ CodeMode = objectgenerator, Final, GenerateAfter = %GenerateConnector ]

Return the SQL statement defined by the SourceQuery XData block, if any.

%GetPropertyInfo

ClassMethod %GetPropertyInfo(Output pInfo As %List) As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %GenerateConnector ]

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.

%OnGetPropertyInfo

ClassMethod %OnGetPropertyInfo(ByRef pInfo As %String) As %Status [ Abstract, Internal ]

If implemented, this method is called by the %GetPropertyInfo method.

%GetKeyFields

ClassMethod %GetKeyFields(Output pKeys As %String) As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %GenerateConnector ]

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.

%GenerateConnector

ClassMethod %GenerateConnector() As %Status [ CodeMode = objectgenerator, Final, GenerateAfter = %OnProcessRecord, Internal ]

Process the model for this connector and create code and additional classes.

%Print

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.

%GetVersion

ClassMethod %GetVersion() As %String [ CodeMode = objectgenerator, Final, GenerateAfter = %GetPropertyInfo, Internal ]

Return a checksum based on the current definition of this connector. This allows consumers of this connector to detect if there have been structural changes to it.

%GetRestrictionClause

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.

OnPage

ClassMethod OnPage() As %Status

Draw the test page.

%ToJSON

ClassMethod %ToJSON(ByRef pParameters) As %Status

Write out all data in JSON format.