Using an XML Document as the Client of a Provider
Go Up to Using XML in Database Applications Index
The Datasnap.Xmlxform.TXMLTransformClient component acts as an adapter to let you use an XML document (or set of documents) as the client for an application server (or simply as the client of a dataset to which it connects via a TDataSetProvider component). That is, TXMLTransformClient lets you publish database data as an XML document and to make use of update requests (insertions or deletions) from an external application that supplies them in the form of XML documents.
To specify the provider from which the TXMLTransformClient object fetches data and to which it applies updates, set the Using Provider Components.
If the provider is on a remote application server, you must use a DataSnap connection component to connect to that application server. Specify the connection component using the Connecting to the Application Server.
Fetching an XML document from a provider
TXMLTransformClient uses an internal TXMLTransform component to translate data packets from the provider into an XML document. You can access this TXMLTransform component as the value of the TransformGetData property.
Before you can create an XML document that represents the data from a provider, you must specify the TXMLTransform stand-alone component. If that transformation includes any user-defined nodes, you will want to supply TransformGetData with an Xml.XmlTransform.TXMLTransform.OnTranslate using a stand-alone TXMLTransform component. If that transformation includes any user-defined nodes, you will want to supply TransformGetData with an Xmlxform.OnTranslate event handler as well.
There is no need to specify the source document for TransformGetData, TXMLTransformClient fetches that from the provider. However, if the provider expects any input parameters, you may want to set them before fetching the data. Use the SetParams method to supply these input parameters before you fetch data from the provider. SetParams takes two arguments: a string of XML from which to extract parameter values, and the name of a transformation file to translate that XML into a data packet. SetParams uses the transformation file to convert the string of XML into a data packet, and then extracts the parameter values from that data packet.
Note: You can override either of these arguments if you want to specify the parameter document or transformation in another way. Simply set one of the properties on Converting XML Documents Into Data Packets.
Once you have configured TransformGetData and supplied any input parameters, you can call the GetDataAsXml method to fetch the XML. GetDataAsXml sends the current parameter values to the provider, fetches a data packet, converts it into an XML document, and returns that document as a string. You can save this string to a file:
var
XMLDoc: TFileStream;
XML: string;
begin
XMLTransformClient1.ProviderName := 'Provider1';
XMLTransformClient1.TransformGetData.TransformationFile := 'CustTableToCustXML.xtr';
XMLTransformClient1.TransFormSetParams.SourceXmlFile := 'InputParams.xml';
XMLTransformClient1.SetParams('', 'InputParamsToDP.xtr');
XML := XMLTransformClient1.GetDataAsXml('');
XMLDoc := TFileStream.Create('Customers.xml', fmCreate or fmOpenWrite);
try
XMLDoc.Write(XML, Length(XML));
finally
XMLDoc.Free;
end;
end;
XMLTransformClient1->ProviderName = "Provider1";
XMLTransformClient1->TransformGetData->TransformationFile = "CustTableToCustXML.xtr";
XMLTransformClient1->TransFormSetParams->SourceXmlFile = "InputParams.xml";
XMLTransformClient1->SetParams("", "InputParamsToDP.xtr");
AnsiString XML = XMLTransformClient1->GetDataAsXml("");
TFileStream pXMLDoc = new TFileStream("Customers.xml", fmCreate || fmOpenWrite);
__try
{
pXMLDoc->Write(XML.c_str(), XML.Length());
}
__finally
{
delete pXMLDoc;
}
Applying updates from an XML document to a provider
TXMLTransformClient also lets you insert all of the data from an XML document into the provider's dataset or to delete all of the records in an XML document from the provider's dataset. To perform these updates, call the ApplyUpdates' method,' passing in
- A string whose value is the contents of the XML document with the data to insert or delete.
- The name of a transformation file that can convert that XML data into an insert or delete delta packet. (When you define the transformation file using the XML mapper utility, you specify whether the transformation is for an insert or delete delta packet.)
- The number of update errors that can be tolerated before the update operation is aborted. If fewer than the specified number of records can't be inserted or deleted, ApplyUpdates returns the number of actual failures. If more than the specified number of records can't be inserted or deleted, the entire update operation is rolled back, and no update is performed.
The following call transforms the XML document Customers.xml into a delta packet and applies all updates regardless of the number of errors:
StringList1.LoadFromFile('Customers.xml');
nErrors := ApplyUpdates(StringList1.Text, 'CustXMLToInsert.xtr', -1);
StringList1->LoadFromFile("Customers.xml");
nErrors = ApplyUpdates(StringList1->Text, "CustXMLToInsert.xtr", -1);