%XML.DataSet extends the %ResultSet class to be SOAP enabled
in order to act as the return value of a WebService method.
The %XML.DataSet returns the result set as a .NET DataSet.
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
}
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.
method Close() as %Status [ Language = objectscript ]
Closes the current result set cursor.
method GetColumnCount() as %Integer [ Language = objectscript ]
Returns the number of columns in the result set.
Each row may be different for %XML.DataSet
method GetColumnHeader(n As %Integer) as %String [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
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
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.
method Next(ByRef sc As %Status) as %Integer [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
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...) [ Language = objectscript ]
Set the arguments to be used for the %ResultSet.Execute.
method WriteSchema() as %Status [ Language = objectscript ]
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 [ Language = objectscript ]
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 [ Language = objectscript ]
Generate hard coded schema that is used for DataSet