XmlDocFactory Class Methods

In this section, the XmlDocFactory class methods are presented in alphabetical order.

Syntax

GetNextXmlDoc(nodeName)

Description

Use the GetNextXmlDoc method to retrieve the next XML subtree matching the given nodeName parameter.

The node name can be a single name, or a list of names separated by a forward slash. For example:

"Transaction" returns an XML subtree with Transaction as the root.
"Transaction/Date" returns an XML subtree in which Date has a parent node Transaction.

Matching occurs when a node name in the input string matches all of the characters in the nodeName parameter. For example:

"Trans" matches nodes in the XML string with those leading characters. For example: Transaction, Transparent, and Transport.
"Trans/Date" matches all Date nodes in the input string that have a parent like Transaction, Transparent, or Transport.

Finally, the wildcard * matches any node. Therefore, "Trans/Date/*" matches any node that has a parent matching Date, which in turn has a parent matching Trans.

Parameters

Field or Control	Definition
`nodeName`	A case-sensitive string containing the identifier for the nodes to find

Returns

An XmlDoc object containing a matching XML subtree, in which case, the IsNull property of the XmlDoc object is set to False.

Otherwise, when nothing is found, the IsNull property of the XmlDoc object is set to True.

Example

Local XmlDocFactory &theXmlDocFactory;
Local XmlDoc &theXmlDoc;
Local string &findString = "Transaction";

&theXmlDocFactory = CreateXmlDocFactory();

&returnbool = &theXmlDocFactory.SetStringToParse(&inputXmlString);

&theXmlDoc = &theXmlDocFactory.GetNextXmlDoc(&findString);

While ( Not &theXmlDoc.IsNull)
   
   rem do something with the XmlDoc;
   
   &theXmlDoc = &theXmlDocFactory.GetNextXmlDoc(&findString);
   
End-While;

Syntax

SetNamespaceString(namespaceString)

Description

For certain XML structures, namespace declarations are separate from nodes using those namespaces. The SetNamespaceString method allows a namespace string to be inserted back into the output document. If this operation is not performed, there can be parsing errors when the output XmlDoc is created.

For example, the following is the input XML to the XmlDocFactory object:

<?xml version="1.0"?>
<ns1:transaction xmlns:qed="http://www.blue.com" xmlns:ns1="http://www.transaction.com">
   <purchaseOrder>
      <qed:elecronics>
         <item>TV</item>
      </qed:elecronics>
   </purchaseOrder>
</ns1:transaction>

The GetNextXmlDoc method is used to extract the electronics subtree:

<?xml version="1.0"?>
<qed:elecronics>
   <item>TV</item>
</qed:elecronics>

The resulting XML is actually invalid, as the namespace information for the prefix qed has been lost.

The following invocation of the SetNamespaceString method results in the namespace info being re-added:

&theXmlDocFactory.SetNamespaceString(" xmlns:qed='http://www.blue.com' ")

Important! There should be leading and trailing spaces in the namespace parameter being set.

The resulting XML document can be parsed:

<?xml version="1.0"?>
<qed:elecronics xmlns:qed="http://www.blue.com">
   <item>TV</item>
</qed:elecronics>

Parameters

Field or Control	Definition
`namespaceString`	The namespace string to be added back into the XML document. Important! There should be leading and trailing spaces in the namespace parameter being set.

Returns

A Boolean value: True if the namespace string is set, False otherwise.

Example

Local XmlDocFactory &theXmlDocFactory;

&theXmlDocFactory = CreateXmlDocFactory();

&returnbool = &theXmlDocFactory.SetStringToParse(&inputXmlString);

&returnbool = &theXmlDocFactory.SetNamespaceString(" xmlns:qed='http://www.blue.com' ");

Local XmlDoc &theXmlDoc;

&theXmlDoc = &theXmlDocFactory.GetNextXmlDoc("qed:elec");

While ( Not &theXmlDoc.IsNull)
   
   rem do something with the XmlDoc;
   
   &theXmlDoc = &theXmlDocFactory.GetNextXmlDoc(&findString);
   
End-While;

Syntax

SetStringToParse(xmlstring)

Description

Use the SetStringToParse method to set the XML string to be parsed by the XmlDocFactory object.

The XmlDocFactory class is not a full-featured XML parser. Strings to be parsed must be well-formed XML; otherwise the parsing will not work. In addition, the XmlDocFactory does not make a copy of the string to be parsed; as a result the string must remain in scope for the duration of processing.

Parameters

Field or Control	Definition
`xmlstring`	A string containing well-formed XML.

Returns

A Boolean value: True if the XML string is set, False otherwise.

Example

Local XmlDocFactory &theXmlDocFactory;

&theXmlDocFactory = CreateXmlDocFactory();

&returnbool = &theXmlDocFactory.SetStringToParse(&inputXmlString);

Local XmlDoc &theXmlDoc;

&theXmlDoc = &theXmlDocFactory.GetNextXmlDoc("Transaction");