|
|
This document is the fourth part of the introduction to TransacXML.
This document describes the way you can create an XML-document using the functions you get when you create a model of the XML-document in TransacXML.
Note that you must model the document in the Plex model before you can create it. You can either do this as a manual process or by using the TransacXML import tool (if you have an XML-schema file or a wsdl file describing the document).
The following description describes how to create an XML document and write it to a file on the disk.
However, exactly the same method is used if you want to create XML-documents when you implement web services. The only difference is the inheritance of the export function.
Before you can start working with the XML document, you need to create an export function. This function initializes the XML environment and handles the saving of the document to a file. The function is created by inheritance from ExportXMLDocument:
| Source Object | Verb | Target Object |
|---|---|---|
| MyExportFunction | is a FNC | ExportXMLDocument |
The function will have the following interface:
The three input parameters allow you to specify:
The xml-declaration is the first line of the XML document - e.g:
<?xml version="1.0" encoding="UTF-8" ?>
The local variable "OutputDocument" contains two fields that are extensively used when calling TransacXML functions. You can see these fields as being an alias for the XML document you are creating.
The ExportXMLDocument creates a memory store, where all of the XML-objects you will be creating can be stored. The identification of this store is available at:
Local/OutputDocument<ObjectStoreReference>
It also creates a parser-document (an object stored in memory, where you can store the tree-structure of the XML before saving it as a file). The identification of this parser-document is available at:
Local/OutputDocument<ObjectDocument>
When you create an XML-document, you will create a tree-structure and add the elements of this structure to the ObjectDocument.
In the edit point "Process xml document", the necessary objects have been initialized and you can start to building the XML-document.
You build the document by calling the InsertRow functions scoped by the XMLElements that corresponds to the complex element you want to insert.
When you call the InsertRow function, you can specify the values for the simple elements and attributes that belong to the complex element.
Apart from this, you must specify which store you want to add the complex element to, which document you want to add it to, and where in the document you want to add it.
All InsertRow functions have three parameters for specifying this information.
ObjectStoreReference
Always map with Local/OutputDocument<ObjectStoreReference>
ObjectDocument
Always map with Local/OutputDocument<ObjectDocument>
ParentElement
If you are inserting the top element in the document, specify Local/OutputDocument<ObjectDocument>
If you are inserting a child to another complex element, specify the [ParentElement].InsertRow/Output<ObjectElement>
So the way to create an XML-document is as follows:
1.
Create the top element of the XML-document by calling the InsertRow function scoped by the corresponding XMLElement.
Specify Local/OutputDocument<ObjectDocument> for the ParentElement parameter.
2.
Work your way down in the document by recursively adding complex elements as child elements of already created complex elements by calling the InsertRow function of the element to insert. Specify the ObjectElement returned by the InsertRow function of the parent element as the input parameter ParentElement.
If a complex element occurs more than once under a parent element, call the InsertRow function of this complex element once for each instance you want to insert.
The order of the calls to the InsertRow functions determines the order of the complex child elements.
As in any other program, you should check whether the called function reports any errors. Like most other Plex functions, you do this by checking the *Returned status after each call. This states whether the call has been successful - but does not state anything about the cause of the error.
In some cases the TransacXML runtime has been able to gather more information about the error. If this information is present, it has been stored in a stack of error-messages.
You can retrieve the information from the stack by calling the function DomServices.ErrorPop repeatedly (as long as the output parameter ExceptionCode2 is successful). This retrieves the errors from the stack.
The example will show how you can create the following document. You do this by building the tree-structure shown here:
Before creating an instance of the document, you need to model in the Plex model.
The example will show the following steps:
This inserts the Race element as the top element of the document. Note that the interface of the Race.InsertRow contains the fields date and name, the values specified for these fields will be inserted as the two attributes shown in the document.
This inserts the Course element as a child of the Race element. The InsertRow function has the two input fields CourseName and Address, which will be inserted as the two simple elements for the complex Course element.
This inserts the Horses element as a child of the Race element.
This inserts three Horse child elements under the Horses element. The Horse.InsertRow function has four input parameters, the values is used to create the Name attribute and the three simple fields that is scoped by each Horse element.
Start by creating the export function:
| Source Object | Verb | Target Object |
|---|---|---|
| CreateHorseXml | is a FNC | ExportXmlDocument |
In the edit point Process XML document, enter the following code:
Call Race.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Local/OutputDocument<ObjectDocument>
Local/OutputDocument<ObjectDocument>
Value: 2010-12-31
Value: New Years Meet
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
Call Race.Course.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Race.InsertRow/Output<ObjectElement>
Local/OutputDocument<ObjectDocument>
Value: The new track
Value: Track Road 123
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
Call Race.Horses.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Race.InsertRow/Output<ObjectElement>
Local/OutputDocument<ObjectDocument>
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
Call Race.Horses.Horse.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Race.Horses.InsertRow/Output<ObjectElement>
Local/OutputDocument<ObjectDocument>
Value: Bonfire
Value: 5000
Value: 1988-01-02
Value: M
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
Call Race.Horses.Horse.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Race.Horses.InsertRow/Output<ObjectElement>
Local/OutputDocument<ObjectDocument>
Value: Faithfull Dobbin
Value: 3500
Value: 1986-05-31
Value: F
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
Call Race.Horses.Horse.InsertRow
Map with:
Local/OutputDocument<ObjectStoreRefence>
Race.Horses.InsertRow/Output<ObjectElement>
Local/OutputDocument<ObjectDocument>
Value: Pegasus
Value: 3000
Value: 1992-06-23
Value: M
If Environment<*Returned status> != <*Returned status.*Successful>
Set Environment<*Returning status> = Environment<*Returned status>
Go Sub Terminate
The TransacXML functions all set the field Environment<*Returned status>.
In the cases where the status is not successful, you will often want more information about the error. The following document describes how the TransacXML runtime stores any errors it detects and how you can retrieve them.
More information about modeling, creating and processing XML
Online documentation - Websydian v6.5