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

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
9	19	25

Summary

Properties
%Message	%Metadata	%PrivateTables	%ROWCOUNT
%ROWID	%ResultColumnCount	%SQLCODE	CaseSensitive
ClassName	Data	DataSetName	DiffGram
NeedSchema	QueryName	RuntimeMode	WriteEmptyDiffgram

Methods
%AddToSaveSet	%ClassIsLatestVersion	%ClassName	%CloseCursor
%ConstructClone	%CreateSnapshot	%DispatchClassMethod	%DispatchGetModified
%DispatchGetProperty	%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty
%Display	%DisplayFormatted	%Execute	%Extends
%Get	%GetData	%GetMetadata	%GetParameter
%IsA	%IsModified	%MetadataGet	%New
%Next	%NormalizeObject	%ObjectModified	%OriginalNamespace
%PackageName	%Prepare	%PrepareMetaData	%Print
%RemoveFromSaveSet	%ResultColumnCountGet	%SendDelimitedRows	%SendODBC
%SerializeObject	%SetModified	%ValidateObject	ClassNameSet
Close	ContainsId	ConvertParameter	Decrypt
Encrypt	EscapeHTML	EscapeURL	Execute
Get	GetColumnCount	GetColumnExtInfo	GetColumnHeader
GetColumnName	GetColumnType	GetData	GetDataByName
GetExtent	GetODBCInfo	GetObject	GetParamCount
GetParamName	GetStatementType	HyperEventCall	HyperEventHead
Include	InsertHiddenField	InsertHiddenFields	IsPrivate
Link	Next	OnHTTPHeader	OnPageError
OnPostHTTP	OnPostHyperEvent	OnPreHTTP	OnPreHyperEvent
Page	Prepare	QueryIsValid	QuoteJS
ResetXML	RewriteURL	RunPropertyMethod	RunQuery
RuntimeModeGet	RuntimeModeSet	SetArgs	SetIdInfo
ShowError	StartTimer	StopTimer	Test
ThrowError	UnescapeHTML	UnescapeURL	WriteSchema
WriteXML	XMLDTD	XMLExport	XMLExportToStream
XMLExportToString	XMLNew	XMLSchema

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 DataSetName as %String(TRUNCATE=1);

The name of the DataSet being returned. Default set in %OnNew.

• property DiffGram as %Boolean [ InitialExpression = 1 ];

True if the data set is to be written in Microsoft DiffGram format.

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

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.

• method Next(ByRef sc As %Status) as %Integer

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

Class Reference IRIS for UNIX 2024.1.2
Documentation Search