Skip to main content

%XML.DataSet

class %XML.DataSet extends %Library.ResultSet, %CSP.Page, %XML.Adaptor

This class represents a .NET DataSet, which is an XML-enabled dataset that you can use in SOAP messages when both the web service and client are based on InterSystems IRIS or when one side uses .NET. Other SOAP vendors do not support datasets and cannot process a WSDL generated by a web service that uses them.

The %XML.DataSet only needs to be instantiated using %New() and then returned as the result of a WebService. The Execute method should not be called. The values of the result set will automatically be retrieved by the WebService mechanism and formatted in XML as a .NET DataSet.

If arguments must be passed to the query for its proper execution, then the SetArgs() method may be used.

The query for the DataSet may be specified either at runtime or at compile time as parameters of a subclass of %XML.DataSet. If the query is specified at runtime, then a .NET untyped DataSet is returned by the SOAP support. If the query is specified by a compile time parameter, then a .NET typed DataSet is returned by the SOAP support.

If you use this class as the value returned by a web method, note that this class is designed to work only with SoapBindingStyle=document and SoapBodyUse=literal, so be sure to set those keywords.

Untyped DataSet

You can return a %XML.DataSet object as an untyped DataSet from a WebService as follows:

ClassMethod GetByName(prefix As %String) As %XML.DataSet [ WebMethod ]
{
    // Return the results of the Person class' ByName query.
    Set result=##class(%XML.DataSet).%New("Sample.Person:ByName")
    Do result.SetArgs(prefix)
    Quit result
}

Note you can bind a %XML.DataSet object to a query by either a) setting the ClassName and QueryName properties or b) passing a string containing the class name and query name (separated by a :) to the %New method.

Dynamic SQL

You can use the %XML.DataSet class to execute dynamic SQL queries using the system-provided %DynamicQuery:SQL query. In this case, use the Prepare() method to supply the text of the query. For example, execute the following to return an untyped DataSet: 

ClassMethod GetBySalary(salary As %Integer) As %XML.DataSet [ WebMethod ]
{
    Set result=##class(%XML.DataSet).%New()
    Do result.Prepare("SELECT ID, Name, Salary FROM Employee WHERE Salary > ?")
    Do result.SetArgs(salary)
    Quit result
}

Typed DataSet

To return a typed DataSet, create a subclass of %XML.DataSet with the NAMESPACE, CLASS and QUERY parameters specified. Assume that the subclass is called MyTypedDataSet, then the following code returns a typed DataSet: 

ClassMethod GetByName(prefix As %String) As MyTypedDataSet [ WebMethod ]
{
    // Return the results of the Person class' ByName query.
    Set result=##class(MyTypedDataSet).%New()
    Do result.SetArgs(prefix)
    Quit result
}

Property Inventory

Method Inventory

Parameters

parameter CLASSNAME;
The class name that contains the query for typed DataSet
parameter DATAONLY = 0;
If DATAONLY is set to true (=1), then the schema and diffgram will not be included in dataset XML output.
parameter LOCATION;
LOCATION - Should be the URL which is the location of the DataSet schema. The url may be absolute or relative to the schema request URL..
parameter NAMESPACE;
The XML namespace for typed DataSets
parameter QUERYNAME;
The query name for typed DataSet
parameter XMLNAME;
Use "DefaultDataSet" as the default DataSet name for untyped DataSets. Use the subclass name as the default DataSet name for typed DataSets.
parameter XMLTYPE;
Use "DataSet" as the type.

Properties

property CaseSensitive as %Boolean [ InitialExpression = 0 ];
CaseSensitive is Boolean property which corresponds to the Microsoft CaseSensitive dataset property.
Property methods: CaseSensitiveDisplayToLogical(), CaseSensitiveGet(), CaseSensitiveIsValid(), CaseSensitiveLogicalToDisplay(), CaseSensitiveLogicalToXSD(), CaseSensitiveNormalize(), CaseSensitiveSet(), CaseSensitiveXSDToLogical()
property DataSetName as %String (TRUNCATE = 1);
The name of the DataSet being returned. Default set in %OnNew.
Property methods: DataSetNameDisplayToLogical(), DataSetNameGet(), DataSetNameIsValid(), DataSetNameLogicalToDisplay(), DataSetNameLogicalToOdbc(), DataSetNameNormalize(), DataSetNameSet()
property DiffGram as %Boolean [ InitialExpression = 1 ];
True if the data set is to be written in Microsoft DiffGram format.
Property methods: DiffGramDisplayToLogical(), DiffGramGet(), DiffGramIsValid(), DiffGramLogicalToDisplay(), DiffGramLogicalToXSD(), DiffGramNormalize(), DiffGramSet(), DiffGramXSDToLogical()
property NeedSchema as %Boolean;
True if the data set is to be written preceded by its schema. Default is 1 for diffgram, else 0.
Property methods: NeedSchemaDisplayToLogical(), NeedSchemaGet(), NeedSchemaIsValid(), NeedSchemaLogicalToDisplay(), NeedSchemaLogicalToXSD(), NeedSchemaNormalize(), NeedSchemaSet(), NeedSchemaXSDToLogical()
property WriteEmptyDiffgram as %Boolean;
True if the dataset is to contain only a diffgram element if there are no rows. The default is to have an empty element with the name of the dataset inside the diffgram element.
Property methods: WriteEmptyDiffgramDisplayToLogical(), WriteEmptyDiffgramGet(), WriteEmptyDiffgramIsValid(), WriteEmptyDiffgramLogicalToDisplay(), WriteEmptyDiffgramLogicalToXSD(), WriteEmptyDiffgramNormalize(), WriteEmptyDiffgramSet(), WriteEmptyDiffgramXSDToLogical()

Methods

method Close() as %Status
Closes the current result set cursor.
method GetColumnCount() as %Integer
Returns the number of columns in the result set. Each row may be different for %XML.DataSet
method GetColumnHeader(n As %Integer) as %String
Returns the column header for column n in the result set. Each row may be different for %XML.DataSet
method GetColumnName(n As %Integer) as %String
Returns the name of column n in the result set. Each row may be different for %XML.DataSet
method GetColumnType(n As %Integer) as %Integer
Returns the type of column n in the result set where type is an integer (CLIENTDATATYPEENUM) associated with the client datatype. Reference %occName for an explanation of the integer values. If the type cannot be determined, 0 (zero) is returned
method GetObject() as %RegisteredObject
If this query contains an object Id then this method opens an object with this Id and returns the object reference. Otherwise it returns a null object reference.
Advance the result set cursor to the next row in the XML tree. Returns 0 if the cursor is at the end of the result set.
method ResetXML() as %Status
Resets the current result set cursor to the beginning of the dataset. This method only works for datasets which have been created by reading XML input.
method RunPropertyMethod(col As %List, method As %String, value As %String) as %String
Call property method (logicalToXSD or XSDToLogical) for the specified column. Column is specified by a column list: $lb(name,xsdType,columnClass,columnProperty,ignoreNull)
method SetArgs(args...)
Set the arguments to be used for the %ResultSet.Execute.
method WriteSchema() as %Status
Write the XML schema for the data rows.
method WriteXML(top As %String, diffGram As %Boolean = "", writeSchema As %Boolean = "", namespaces As %XML.Namespaces, local As %Boolean, ignoreNull As %Boolean) as %Status
Write the data rows as XML with optional preceding schema.
classmethod XMLDTD(top As %String, format As %String, input As %Boolean, ByRef dtdlist) as %Status
No DTD available for DataSet
classmethod XMLSchema(top As %String, format As %String, namespacePrefix As %String = "", input As %Boolean, refOnly As %Boolean, ByRef schema) as %Status
Generate hard coded schema that is used for DataSet

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab