Online documentation - Websydian v6.0

Users Guide | Patterns Reference | WebsydianExpress | Search

 
» Related Information

DomServices Function Suite

Understanding the ObjectStore

Error handling

TransacXML Implementation Guide


This document explains how to build a XML model in TransacXML. Most often this XML model has already been defined in another format, e.g. a DTD, XML schema, or the XML model is just defined with a sample XML document.

Even though this document describes the conversion process when transforming a DTD or sample XML document into a XML model in CA Plex, the information will also be useful when designing XML models from scratch in CA Plex.

Information in the AllFusion Plex Model

A DTD or XML schema will contain much more information about the XML documents they describe than is necessary for the corresponding CA Plex model. The CA Plex model only needs the following information:

This is the only information that needs to be extracted from the DTD or XML schema when carrying out the modeling process.

Data Stored in the XML Document

In TransacXML, the following ways of representing data in an XML document are supported:

Each of these data representations will be described below in more detail.

Data in Attributes

TransacXML can retrieve data from element attributes:

XML Example
<person name="Peter" age="27"></person>
 

In TransacXML, attributes are represented as fields inheriting from the abstract field AttributeField.

Attributes are represented as fields inheriting from AttributeField.

Data in Simple Elements

TransacXML can retrieve data from the value of a text node being the only child of an element:

XML Example
<person>
  <name>Peter</name>
  <age>27</age>
</person>


Simple Elements

Simple elements are elements with exactly one child node that is a text node.

In TransacXML, simple elements are represented as fields inheriting from the abstract field ElementField or RepeatingElementField (depending on how many times they are allowed to occur).

In the above example, the elements name and age are simple elements whereas the element person is a complex element.

The following restrictions apply to this type of data representation:

Simple Elements are represented as fields inheriting from ElementField or RepeatingElementField.

Data in Complex Elements

TransacXML also supports a combination of the two data representations described above:

XML Example
<person name="Peter">
  <age>27</age>
</person>
 

An XML construction carrying a sub structure is defined as a complex element in TransacXML, and it is represented as an entity inheriting from XmlElement or XmlRepeatingElement. The structure scoped under the complex element is either simple elements (represented as entity fields), or more complex elements (represented as scoped entities).

The following restriction apply to this type of data representation: 

An attribute is not allowed to have the same name as any of the simple elements. However, an attribute can have the same name as elements that do not have the role as simple elements. Consider these examples:

Example 1

XML Example
<person name="Peter">
  <name>James</name>
</person> 

is illegal since the attribute and the simple element carry the same name.

Example 2

XML Example
<person name="Peter" job="Typist">
  <job description="A typer"></job>
</person>

is legal since the job element is not a simple element.

Complex Elements are represented in TransacXML as entities - inheriting from XmlElement or XmlRepeatingElement.

Repeated Elements

TransacXML supports elements that are repeated multiple times within the scope of a particular parent element:

Example 1

XML Example
<receipt>
  <item>Milk</item>
  <item>Sugar</item>
  <item>Salt</item>
</receipt>

Example 2

XML Example
<department>
  <person>
    <name>Peter Jenkins</name>
  </person>
  <person>
    <name>Siobhan Anderson</name>
  </person>
</department>

In example 1, the simple element item is repeated. In example 2, the complex element person element (that scopes the simple element name) is repeated. Examples 1 and 2 represent two different cases when converting into CA Plex objects and triples.

How to Create XML Model

This section contains information about how to model the XML document structure into triples and objects in the CA Plex model. Typically the XML model is created from either a DTD or an XML document sample, so for each triple and object there will be examples on how the corresponding DTD or XML document snippet look like.

The creation of triples and objects includes two basic activities:

When the modeling process has been completed, the CA Plex model will contain an entity with the same name as the document element (root element) of the XML document. This entity scopes entities which themselves scope entities according to the element structure of the XML document.

To carry out the modeling process go through the steps specified below (each step is explained in detail in the following sections):

  1. Specify the root element of the XML document
    Model the document element (root element).
  2. Specify element structure
    Identify the structure of elements in the XML document or DTD.
  3. Specify data fields
    For each entity created specify the data fields connected to that entity.

Declaration of Document Element (Root Element)

XML documents have exactly one root element (the document element). The modeling of the document element into an entity in CA Plex is the starting point of the modeling process. Often, the first declaration in a DTD will be the declaration of the document element. 

Identify the document element declaration in the DTD this way: 

Find the one DTD declaration which declares an element that does not occur within the parentheses of another element declaration.

Consider the following DTD declaration:

DTD Example

<!ELEMENT MyDocumentElement (Child1,…,ChildN)>

XML Example

<?xml version="1.0" encoding="utf-8"?>
<MyDocumentElement>

  <Child1>...</Child1>

    .....
  <Childn>...</Childn>

</MyDocumentElement>

If no element declaration can be found in which MyDocumentElement occurs within the parentheses, then MyDocumentElement is the document element of XML documents described by the DTD being converted. For XML documents the document element is the top element.

When the document element has been identified (e.g. MyDocumentElement) create the following triple:

Source Object Verb Target Object
MyDocumentElement is a ENT XmlElement

Structure Declarations

The organization of elements into parents and children is specified using the following DTD declarations:

DTD Example
<!ELEMENT MyParent (MyChild1,…,MyChildN)>
<!ELEMENT MyChild1 (…,…)>

<!ELEMENT myChildN (…,…)>

If MyChild elements are later declared using the <!ELEMENT MyChild (#PCDATA) > declaration, MyChild is a simple element and should thus be represented as a field in the CA Plex model. Refer to the data field section for further information. This applies to all declarations mentioned in the present section.

Information about whether the element can occur more than once should be imported into the CA Plex model. There are three cases to consider:

The quantity indicators ?, +, and * in the DTD declaration determine how many times an element can occur within the scope of its parent. ? specifies that the element can occur zero or one time. + specifies that the element can occur once or more times. * specifies that the element can occur zero or more times. 

Below, the corresponding triples are specified for each of the mutually exclusive cases.

Child Element Occurs Once

If the element MyChild is declared using no quantity indicators the corresponding element occurs once within the scope of its parent. The corresponding DTD declarations have the following structure:

DTD Example
<!ELEMENT MyParent(MyChild)>
<!ELEMENT MyChild(MyGrandChild)>
XML Example

<MyParent>

  <MyChild>

    <MyGrandChild>

    </MyGrandChild>

  </MyChild>

</MyParent>

Suppose an entity MyParent has already been created then the following triples should be created:

Source Object Verb TargetObject
MyParent

 

is a ENT XmlElement
includes ENT MyChild
MyChild is a ENT XmlElement

Child Element Can Occur More than Once

If either of the quantity indicators + or * is used when declaring child elements, the child element can occur more than once. 

Such declarations have the following structure:

DTD Example
<!ELEMENT MyParent(MyChild+) >
<!ELEMENT MyChild(MyGrandChild)>

or

<!ELEMENT MyParent(MyChild*)>
<!ELEMENT MyChild(MyGrandChild)

XML Example

<MyParent>

  <MyChild>

    <MyGrandChild>

    </MyGrandChild>

  </MyChild>

  <MyChild>

    <MyGrandChild>

    </MyGrandChild>

  </MyChild>

</MyParent>

In this case, the following triples should be declared:

Source Object Verb Target Object
MyParent is a ENT XmlElement
includes ENT MyChild
MyChild is a ENT XmlRepeatingElement

Optionality for Complex Elements

If a complex element is optional, this is handled by specifying the option Optional VAL YES on the scoped function ElementOptions.

If the element MyChild is declared using the quantity indicator ? the corresponding element occurs at the most once within the scope of its parent. The corresponding DTD declarations have the following structure:

DTD Example
<!ELEMENT MyParent(MyChild?) >
<!ELEMENT MyChild(MyGrandChild)>
XML Example

<MyParent>

</MyParent>

Suppose an entity MyParent has already been created then the following triples should be created:

Source Object Verb TargetObject
MyParent

 

is a ENT XmlElement
includes ENT MyChild
MyChild is a ENT XmlElement
MyChild.ElementOptions option NME

...value SYS

Optional
Yes

Complex Elements with Long Names

Complex elements are modeled in the CA Plex model as entities with the same names as their XML element counterparts. However, the maximum length of objects in AllFusion Plex is 32 characters. A complex element with a name longer than 32 characters requires an extra inheritance triple to be created.

All names not conforming to the AllFusion Plex naming scheme should be treated as long names, even if they are shorter than 32 characters. 

Suppose a DTD declaration specifies an element with the name MyLongElementName where MyLongElementName is longer than 32 characters.

First, find a short name (MyShortElementName) to represent the element internally in the CA Plex model.

Now specify triples as specified above, depending on whether or not the element can occur more than once. Use the MyShortElementName when creating the triples.

An extra inheritance triple should now be created:

Source Object Verb Target Object
MyShortElementName is a ENT LongName

Inheritance from the abstract LongName entity yields a source code object LongName scoped to MyShortElementName.

In the large property of this source code object specify the long name of the element (MyLongElementName). 

Only the element itself with a long name must inherit from LongName.

Example

Consider the following DTD and XML document

DTD Example
<!ELEMENT MyRootElement (ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong)>
<!ELEMENT ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong (MyChild)>
<!ELEMENT MySimpleElement (#PCDATA)>
XML Example
<MyRootElement>
  <ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong>
    <MyChild>
      <MySimpleElement>Text can be put here</MySimpleElement>
    </MyChild>
  </ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong>
</MyRootElement>

Let the entitiy equivalent to the XML element with the rather elaborate name ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong inherit from the LongName entity. In the CA Plex model a name that conforms to the CA Plex standards, e.g. ThisElementLong, should be specified for the entity.

The following should be specified in the respective LongName source code object:

ThisElementHasANameWhichIsWellOverThirtyTwoCharactersLong

The XML element MyChild is specified exactly as if its parent did not had a long name.

Namespaces for Complex Elements

In order to specify that a complex element belongs to a namespace the entity representing the complex element must inherit from the enity NamespaceAware.

Consider the following DTD and XML document:

DTD Example
<!ELEMENT MyParent(...) >

<!ATTLIST MyParent xmlns CDATA #FIXED "http://www.websydian.com/ns">

XML Example

<MyParent xmlns="http://www.websydian.com/ns">

  ...

</MyParent>

To specify that the XML element MyParent belongs in a namespace the following steps must be followed:

  1. Add the following triples to the MyParent entity:
  2. Source Object Verb Target Object
    MyParent is a ENT NamespaceAware
    XmlElement
  3. In the source code object MyParent.Namespace specify the name of the namespace: http://www.websydian.com/ns.
  4. Optionally specify a prefix for the element in the source code object MyParent.Prefix. Please note that this prefix is only used when creating MyParent elements. In most cases the prefix should be left blank.

Please be aware of that namespace definitions in the XML model are inherited. This means that all descendant elements to MyParent also belongs to the namespace http://www.websydian.com/ns. More information can be found here.

For an introduction to namespaces in TransacXML please refer to this document.

Data Fields and Their Representation in the XML Document

TransacXML supports three representations of data:

Information about the individual data fields' representation in the XML document must also be present within the CA Plex model. The three types of data field representation will now be dealt with in turn. 

Data in Attributes

Data represented in attributes have DTD declarations with the following structure:

DTD Example
<!ELEMENT MyParent (…)>

<!ATTLIST MyParent (…)
AttrData1 CDATA #REQUIRED

AttrDataN CDATA #REQUIRED >

The keyword #REQUIRED is an optionality keyword indicating that the attribute must be present in the element. The other optionality keyword is #IMPLIED indicating that the attribute is optional in the element. The optionality keywords should be disregarded in the conversion process.

Assuming the MyParent entity has already been created, create triples as specified below. For each of the attributes declared in the ATTLIST declaration for MyParent, create the following triples:

Source Object Verb Target Object
MyParent is a ENT XmlElement
has FLD MyParent.Fields.AttrDataN
MyParent.Fields field FLD AttrDataN
MyParent.Fields.AttrDataN is a FLD AttributeField

Remember to substitute the actual name of the attribute for AttrDataN when creating the triples. 

Data in Simple Elements

TransacXML uses child elements with a text node as its only child (simple elements) to hold data in equivalence with data in attributes. As was the case with non-simple elements, there are two cases to consider:

Simple Element Occurs at the Most Once

Simple elements occurring at the most once within the scope of their parents are declared using one of the the two following pairs of DTD declarations (The simple element MyChild occurs at the most once):

DTD Example
<!ELEMENT MyParent (MyChild) >
<!ELEMENT MyChild (#PCDATA) >
 

or

<!ELEMENT MyParent(MyChild?) >
<!ELEMENT MyChild (#PCDATA) >
XML Example
<MyParent>
  <MyOnlyChild>I can occur only once</MyOnlyChild>
</MyParent>

The pairs are converted equivalently into triples in the AllFusion Plex model.

When converting a particular  DTD, keep in mind that the two declarations in each pair do not necessarily occur as two consecutive declarations in the DTD.

Assuming the entity MyParent has already been created, create triples as specified below to reflect this in the Plex model. For each simple child element create the triples:

Source Object Verb Target Object
MyParent is a ENT XmlElement
has FLD MyParent.Fields.MyChild
MyParent.Fields Field FLD MyChild
MyParent.Fields.MyChild is a FLD ElementField

Remember to substitute the real name of each element for MyChild when creating the triples.

Simple Elements Can Occur More Than Once

Simple elements which can occur more than once within the scope of their parent elements are declared using one of the two following DTD declaration pairs (The simple element MyChild can occur more than once):

DTD Example
<!ELEMENT MyParent (MyChild+) >
<!ELEMENT MyChild (#PCDATA) >
 

or

<!ELEMENT MyParent(MyChild*) >
<!ELEMENT MyChild (#PCDATA) >
XML Example
<MyParent>
  <MyChild>I can occur multiple times</MyChild>
  <MyChild>It's true!</MyChild>
  <MyChild>It really is</MyChild>
</MyParent>

The pairs are converted equivalently into triples in the CA Plex model.

Assuming the entity MyParent has already been created, create triples as specified below to represent repeating simple elements in the Plex model. For each repeating simple child element create the following triples:

Source Object Verb Target Object
MyParent has FLD MyParent.Fields.MyChild
MyParent.Fields field FLD MyChild
MyParent.Fields.MyChild is a FLD RepeatingElementField

Remember to substitute the real name of the child element for MyChild when creating the triples.

Example of implementing and using the RepeatingElementField check the RepeatingElementFieldExample.

Simple Elements are optional

If a simple element is optional, i.e. it can occur zero or once (in the DTD written as ?), or zero or multiple times (written as *), this is represented in the model using the standard Optionality SYS triple:

Source Object Verb Target Object
MyParent has FLD
...optionality
MyParent.Fields.MyChild
Optional

This is the same for fields inheriting from either ElementField or RepeatingElementField.

Please note that the optionality triple only influences the generation of W3C-schemas and DTD's.

The optionality triple does not ensure that an empty element or attribute field is created if the null value is specified for the field.

Combinations of the Above Data Representations

Often, all three types of data representations described above are present within the scope of the same element. This situation is reflected in the DTD as a combination of the DTD declarations dealt with in the previous sections.

Example

Consider this XML document excerpt:

DTD Example
<!ELEMENT shop (city,employee*)>
<!ELEMENT city (#PCDATA) >
<!ELEMENT employee (#PCDATA) >
<!ATTLIST shop country CDATA #REQUIRED
               name    CDATA #REQUIRED>
XML Example
<shop name="Tesco" country="UK">
  <city>Worcester</city>
  <employee>James Johnson</employee>
  <employee>Peter Jenkins</employee>
</shop>

Here, the element shop uses both attributes and simple elements to contain data. There are two types of simple elements: The simple element city occurs only once, the element employee occurs more than once. Consequently, the two simple elements city and employee yield different triples in the AllFusion Plex model.

Source Object Verb Target Object
shop is a ENT XmlElement
has FLD shop.fields.city
has FLD shop.fields.name
has FLD shop.fields.country
has FLD
...optionality
shop.fields.employee
Optional
shop.fields.name is a FLD AttributeField
shop.fields.city is a FLD ElementField
shop.fields.country is a FLD AttributeField
shop.fields.employee is a FLD RepeatingElementField

Attributes and Simple Elements with Long Names

The attributes and simple elements declared in the DTD are modeled into fields in the CA Plex model. The model fields carry the same names as those of their DTD counterparts. When a simple element or an attribute is declared which name is longer than 32 characters, an extra inheritance triple has to be created in the CA Plex model.

All names not conforming to the AllFusion Plex naming scheme should be treated as long names, even if they are shorter than 32 characters. 

Suppose a DTD declaration specifies an attribute or a simple element with the name MyLongName where MyLongName is longer than 32 characters.

First, find a short name (MyShortName) to represent the element in the CA Plex model.

Now specify triples as specified above, depending on whether or not the element can occur more than once. Use the MyShortName when creating the triples.

An extra inheritance triple should now be created:

Source Object Verb Target Object
MyLongName is a FLD LongName

Inheritance from the abstract LongName field yields a source code object LongName scoped to the MyLongName field.

In the large property of the LongName source code specify the real name of the attribute/simple element.

Example

Consider a DTD declaring an element with a long name attribute:

<MyElement ThisAttributeHasANameWellOverThirtyTwoCharactersLong="Data"> </MyElement>

First, a short name ThisAttribute is used as the name of the model field. Then inheritance from the LongName abstract field is specified.

In the large property of the LongName source code object scoped to ThisAttribute, now specify the real long name of the attribute:

ThisAttributeHasANameWellOverThirtyTwoCharactersLong

Namespaces for Attributes and Simple Elements

Namespaces are specified for attributes and simple elements by inheriting from the field NamespaceAware.

Consider the following DTD and XML document:

DTD Example
<!ELEMENT MyParent(MySimpleElement) >

<!ATTLIST MyParent xmlns:p CDATA #FIXED "http://www.websydian.com/ns"
   p:AttrData CDATA #REQUIRED>

<!ELEMENT p:MySimpleElement (#PCDATA)>

XML Example

<MyParent xmlns:p="http://www.websydian.com/ns"

        p:AttrData="attrval">

  <p:MySimpleElement>Test</p:MySimpleElement>

</MyParent>

To specify that AttrData and MySimpleElement belongs to the namespace http://www.websydian.com/ns simply let the fields representing the simple element and attribute inherit from NamespaceAware.

The table below show total set of triples neccessary in order to create the above simple elements and attributes in the given namespace:

Source Object Verb Target Object
MyParent is a ENT XmlElement
has FLD MyParent.Fields.AttrData
MyParent.Fields.MySimpleElement
MyParent.Fields field FLD AttrData
MySimpleElement
MyParent.Fields.AttrData is a FLD AttributeField
NamespaceAware
MyParent.Fields.MySimpleElement is a FLD ElementField
NamespaceAware

The inheritance from the field NamespaceAware will have the effect that two source code objects are scoped to the fields AttrData and MySimpleElement:

  1. Namespace
    This source code object should contain the namespace that the field belongs to. In this example this is the URI http://www.websydian.com/ns.
  2. Prefix
    This source code object contains the prefix to be used when TransacXML creates attributes/simple elements. In most cases this should be left blank and a value should only be specified if it is required to use a specific prefix.

Although namespaces for attributes and simple elements are specified in exactly the same way there is one fundamental difference: If no namespace is specifed for a simple element, then the simple element will inherit the namespace from the scoping complex element, whereas attributes do not inherit the namespace defintion. More information can be found here.

For an introduction to namespaces in TransacXML please refer to this document.

Specifying Null Value Literals

When retrieving data from an XML document, it may happen that a particular attribute or simple element is not present in the XML document, for instance if it has been declared as optional in the DTD. Optional attributes/simple elements should always be converted into AllFusion Plex fields.

If data corresponding to a particular AllFusion Plex field is not present in the XML document being read,  the field will contain a null value when execution returns from a TransacXML SingleFetch or FlatView call. 

When an attempt is made to retrieve data (using either of the TransacXML functions SingleFetch or FlatView) from an XML element that is not present in the XML document (e.g. because the element is optional), all the data fields specified for that element will contain their respective null values. 

By default, the null value literal is the empty string ( *Blank ). However, the null value literal can be overridden by the Websydian developer. Each field in the entity structure created as a result of the modeling process scopes a value Null. In this value, specify the desired literal to be returned for the field in question.

Example

Take a look at this excerpt from an XML document:

<MyElement>
  <MyOptionalSimpleElement>Data</MyOptionalSimpleElement>
</MyElement>

The modeling process results in an entity MyElement whose Fields function scopes a field MyOptionalSimpleElement. This field has a Null value. Now suppose that the string "MyNullLiteral" has been specified as the literal of the Null value.

If the MyOptionalSimpleElement simple element is not present in an XML document being read, the corresponding AllFusion Plex field will contain the string "MyNullLiteral" when execution returns from the SingleFetch call.

The Choice Construct

This section describes how to convert the choice construct in the DTD into CA Plex triples and objects.

The choice construct looks like this:

<!ELEMENT MyParent (a|b)>

The choice symbol (|) indicates that either a or b can occur as children of MyParent.  

The CA Plex model needs information about which elements it can encounter when retrieving data from the corresponding XML document. In other words, it needs to know the set of all possible choices. Therefore, what should be mapped to the CA Plex model is the union of all elements in the choice construct. In the above example, both of the child elements a and b should be converted into triples in the CA Plex model.

Tables of Conversion

This section contains tables that describe the different cases that can be met in a DTD or existing XML document, and how this is converted into a TransacXML representation in CA Plex.

Simple Element

Occurs exactly once

Occurs zero or once Occurs once or many Occurs Zero or many
DTD snippet MyChild MyChild? MyChild+ MyChild*
Inheritance ElementField ElementField RepeatingElementField RepeatingElementField
Describing Triple Parent has MyChild Parent has MyChild
...optionality Optional
Parent has MyChild Parent has MyChild
...optionality Optional
Sample DTD <!ELEMENT Parent (MyChild)>
<!ELEMENT MyChild (#PCDATA)>
Sample XML document <Parent>
        <MyChild>data</MyChild>
</Parent>
Sample triples
Parent is a ENT XmlElement
has FLD MyChild
MyChild is a FLD ElementField

 

Attribute Occurs exactly once Occurs zero or once
DTD snippet MyAttribute #Required MyAttribute #Implied
Inheritance AttributeField AttributeField
Describing Triple Parent has MyAttribute Parent has MyAttribute
...optionality Optional
Sample DTD <!ELEMENT parent ()>
<!ATTLIST parent MyAttribute CDATA #Required>
Sample XML document <Parent MyAttribute="mydata">
</Parent>
Sample triples
Parent is a ENT XmlElement
has FLD MyAttribute
MyAttribute is a AttributeField

 

Complex Element Occurs exactly once Occurs zero or once Occurs once or many Occurs Zero or many
DTD snippet MyChild MyChild? MyChild+ MyChild*
Inheritance XmlElement XmlElement XmlRepeatingElement XmlRepeatingElement
Describing Triple (none) MyChild.ElementOptions option Optionality VAL YES (none) MyChild.ElementOptions option Optionality VAL YES
Sample DTD <!ELEMENT Parent (MyChild)>
<!ATTLIST Parent MyAttribute CDATA #Required>
<!ELEMENT MyChild (GrandChild)>
<!ELEMENT GrandChild (#PCDATA)>
Sample XML document <Parent>
        <MyChild MyAttribute="data">
                <GrandChild>data</GrandChild>
        </MyChild>
</Parent>
Sample triples
Parent is a ENT XmlElement
has ENT MyChild
MyChild is a ENT XmlElement
has FLD GrandChild
MyAttributeField
GrandChild is a FLD ElementField
MyAttribute is a FLD AttributeField

How to Create an XML Document

In order to process/create an XML document the following functions must be called in the described sequence.

For further information on each of these functions check the DomServices Function Suite

  1. DomServices.InitializeDom
    Initializes the DOM layer. It is only necessary to call this function once.
  2. DomServices.CreateDocument
    Creates an empty XML document in memory. Call this function for every document that must be processed/created.
  3. DomServices.LoadDocumentFromFile (optional)
    This function is called in order to process an XML document previously written to a file. Please note that while this function creates a DOM parse tree for the document in the file, then it is still necessary to call the function CreateDocument before the file is loaded with this function.
  4. Call the functions to process the XML document.
  5. DomServices.SaveDocumentToFile (optional)
    Takes the parameters FileName, Encoding, and Version. The XML document in memory is then written to the file specified by FileName, with the Encoding and Version parameters written as the first line. The XML document is encoded in the character set specified by the Encoding parameter.
  6. DomServices.DestroyDocument
    Frees all resources associated with the XML document. There should be a call to this function for every call to CreateDocument.
  7. DomServices.TerminateDom
    Should be called when all processing of XML documents is completed. This function should be called once for each call to the InitializeDom function.

ExportXMLDocument

Inherit from ExportXMLDocument to get a function with the framework of doing exports to XML documents. Combined with ImportXMLDocument the developer is enabled to both import and export XML documents in the same function.

The ExportXMLDocument function takes input regarding the XML document to be created (Filename, encoding, and xml version). If the filename is *blank the function does not save the document to file. Useful when doing Web Services with WsySoap.

E.g.

Source Object Verb Target Object Comments
MyExportDataToXML is a FNC ExportXMLDocument  
MyProcessXMLDocument is a FNC ExportXMLDocument
ImportXMLDocument
 

Please refer to the XML tutorial for an example on how to use ExportXMLDocument.

ImportXMLDocument

Inherit from ImporttXMLDocument to get a function with the framework of doing import from XML documents. Combined with ExportXMLDocument the developer is enabled to both import and export XML documents in the same function.

The ImportXMLDocument function takes input regarding the XML document to be processed (Filename). If the filename is *blank the function does not load any file. Useful when doing Web Services with WsySoap.

E.g.

Source Object Verb Target Object Comments
MyImportDataFromXML is a FNC ImportXMLDocument  
MyProcessXMLDocument is a FNC ExportXMLDocument
ImportXMLDocument
 

Please refer to the XML tutorial for an example on how to use ImportXMLDocument.

TraverseAndFetch

The TraverseAndFetch functions are used to navigate through the XML document, fetch all of the data and make the data available in a local variable.

The following triples assumes that an XML document, where the top element is called MyTopElement, has been defined in the Plex model.

Source Object Verb Target Object Comments
MyTraverseFunction is a FNC TraverseTopFunction  
MyTraverseFunction replaces

...by

XMLElement.TraverseAndFetch

MyTopElement.TraverseAndFetch

 

Enter the processing needed for the data retrieved for each XMLElement in the edit point Handle Element in the TraverseAndFetch function scoped by the XMLElement.

The function will enter the edit point once for each instance of the XMLElement in the document. The data for the XMLElement is placed in the local variable View.

Generate and build MyTraverseFunction and all of the functions scoped by the XMLElements, which are part of the document if these functions have not already been built.

See the Tutorial for more information concerning the necessary library packages etc. if these have not already been built.

Call the MyTraverseFunction - and the document will be processed.

Transferring parameters

When calling the TraverseAndFetch function of a child element (from TraverseAndFetch function scoped by the parent element) the following local variables are used for mapping the input for the called TraverseAndFetch functions:

  1. Local.Reference
  2. Local.ParameterData
  3. Local.View
  4. Input.ParentData

The variable Reference contains the reference to the parent element. This is populated automatically and should never be changed or have fields added.

The variable ParameterData is empty.

The Variable View contains the data read from the current element.

The Input.ParentData variable contains the data transferred from the calling function.

When a TraverseAndFetch function needs a new input parameter do the following:

Add the field/fields to the called TraverseAndFetch function's Input.ParentData variable

If the value should be taken from the parent element nothing further is needed.

If the data should be taken from the Input.ParentData of the calling function nothing further is needed.

If the data is not present in the Input.ParentData or the Local.View - add the field to the Local.ParameterData variable and populate the field in the action diagram.