Class %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:

or, alternatively, you can implement the %OnGetSourceResultSet callback method. This method should create, prepare, and execute an %SQL.Statement and return the resulting ResultSet.

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:

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
%%OIDGet	%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	HyperEventBody	HyperEventCall	HyperEventFrame
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.


[BASEXML] > [%DeepSee] > [DataConnector]		Private Storage