XML Functions

There are four types of XML definitions available in AMT, which are XML, XMLNode, XMLNodes and XMLNamespaceManager. Each has to be defined first in a form, report or dll before its functionality can be used inside that specific object. So in the local definitions section of the concerned object you can add one or more of the following definitions:

<Xml>                 : xml
<Xmlnode>            : xmlnode
<Xmlnodes>            : xmlnodes
<XmlNamespaceManager> : xmlnamespacemanager

Please note that these definitions may not be placed inside a structure. You are also not allowed to do a redefine on these function variables or to define them as arrays.

When RESOK is set to False upon returning from a function, complementary information can be found in the system item GETLASTRESULT.


Comments placed in the Lion code will be included in the XML code.


Complete reports with examples to produce and consume an XML can be found on: XML examples. An example of how to produce an XML with Namespaces is available on the page: Producing XML with Namespaces. How to consume an XML with Namespaces is explained via an example on the page: Consuming XML with Namespaces.

XML


Saving an XML document with a buffer size greater than the maximum of 2147483647 bytes is not possible. This is a limit that originates from the .NET runtime.

The following functions and properties are available for the XML option:

Function	Description
ADD	Adds a new root node (XMLNode) in memory.
	Use:
	<Xml>.ADD (<Node name> [, <namespaceUri>] )
	<Node name>	Name for the XML root node.
	<namespaceUri>	Optional namespaceURI (string literal or alphanumeric variable) to declare a namespace in the root node.
	Example: MyRootNode := MyXML.ADD('main_node')
	Example with a default namespace: MyRootNode := MyXML.ADD('main_node', 'www.example.com/xml' ) For a more extensive example see: XML Namespaces.
CLEAR	Removes XML from memory.
	Use:
	<Xml>.CLEAR () [RESULTOKTO <Variable>]
	RESULTOKTO	Directs the result status to the specified <Variable> (instead of using the system item RESOK).
	<Variable>	The name of a Boolean or alphanumeric variable.
FILENAME	Returns the file system path of the file that was loaded into the DOM using the Load method or an empty string if no file was loaded since the DOM was created, does not set ResOk.
	Use:
	<Xml>.FILENAME
GETTEXT	This function can get an XML string from the xml that is in memory.
	Use:
	<Xml>.GETTEXT [RESULTOKTO <Variable>]
	Example:XmlAsString := MyXML.GetText

LOAD	Loads the specified XML file in memory.
	Use:
	<Xml>.LOAD (<Filename>) [RESULTOKTO <Variable>]
	<Filename>	Specification (string) to point to the XML file that must be loaded into memory.
	RESULTOKTO	Directs the result status to the specified <Variable> (instead of using the system item RESOK).
	<Variable>	The name of a Boolean or alphanumeric variable.

NAMETABLE	Holds XML attributes and element names after an XML was loaded, which are needed for the XMLNameSpaceManager.
	Use:
	<Xml>.NAMETABLE
	Example: NameSpaceManager.NameTable := MyXML.NAMETABLE For a more extensive example see: Consuming XML with Namespaces.

PARSE	This function can parse an XML string.
	Use:
	<Xml>.PARSE (<XML String>) [RESULTOKTO <Variable>]
	Example:MyXML.Parse('<?xml version="1.0"?><root_element><element1>1</element1><element2>t2</element2></root_element>')

ROOT	Returns the XMLNode that indicates the root element (readonly).
	Use:
	<Xml>.ROOT
	Example: MyNode := MyXML.ROOT

SAVE	Stores the XML that is in memory into the specified file. Note: The maximum buffer size is 2147483647 bytes. This is a limit that originates from the .NET runtime.
	Use:
	<Xml>.SAVE (<Filename> [,<useBOM>]) [RESULTOKTO <Variable>]
	<Filename>	Specification (string) to point to the XML file into which the XML must be stored.
	<useBOM>	By default an UTF BOM marker is added to the XML file. Setting this optional (Boolean) parameter to false will omit this marker from the XML file.
	RESULTOKTO	Directs the result status to the specified <Variable> (instead of using the system item RESOK).
	<Variable>	The name of a Boolean or alphanumeric variable.
SETXMLDECLARATION	This defines the first node in any complete XML document.
	Use:
	<Xml>.SETXMLDECLARATION (<Version>, <encoding>, [<standalone>])
	<Version>	XML specification. Must be “1.0”. There is also an XML 1.1 specification but this is not (yet) supported by the .NET Framework.
	<Encoding>	Identifies which encoding is used to represent the characters in the document. This must be a known encoding name.
	<Standalone>	Whether a document relies on information from an external source, such as external document type definition (DTD), for its content.

XMLNode

The following functions and properties are available for the XMLNode option:

Function	Description
ADD	Adds a new node under the selected node.
	Use:
	<Xml>.ADD (<Name> [, <namespaceUri>] )
	<Name>	Name for the new node.
	<namespaceUri>	Optional namespaceURI (string) to specify a namespace in the new node.
	Example: MyNodes := MyNode.ADD('New_node')
	Example with namespace: MyNodes := MyNode.ADD('mn:New_node', 'www.example.com/xml' ) For a more extensive example see: XML Namespaces.
ADDNAMESPACEDECLARATION	If a single (default) namespace is not enough, more namespaces can be declared on any element (not just the root element).
	Use:
	XmlNode.AddnamespaceDeclaration (<prefix>, <namespaceUri>)
	<prefix>	prefix for the new namespace
	<namespaceUri>	URI of the namespace.
	For an example see: XML Namespaces.

ATTRIBUTE.ADD	Adds an attribute to the node.
	Use:
	<Xmlnode>.ATTRIBUTE.ADD (<Name>, <Value>) [RESULTOKTO <Variable>]
	<Name>	Name for the new attribute.
	<Value>	Value for the new attribute.
	RESULTOKTO	Directs the result status to the specified <Variable> (instead of using the system item RESOK).
	<Variable>	The name of a Boolean or alphanumeric variable.
ATTRIBUTE.COUNT	Returns an integer that indicates the number of attributes on the specified node (readonly).
	Use:
	<Xmlnode>.ATTRIBUTE.COUNT
ATTRIBUTE.NAME	Returns a string that indicates the name of the requested attribute on the specified node (readonly).
	Use:
	<Xmlnode>.ATTRIBUTE[<Index>].NAME
	<Index>	Index number (1 or higher) for the concerned attribute.

ATTRIBUTE.VALUE	Returns or sets the value (String) of requested attribute on the specified node. Index is based from 1 up.
	Use:
	<Xmlnode>.ATTRIBUTE[<Index>].VALUE
	<Index>	Index number (1 or higher) for the concerned attribute.
	Example:MyNode.ATTRIBUTE[2].VALUE := MyNode.ATTRIBUTE[2].VALUE + ' EXTRA'
FIRSTCHILD	Returns the XMLNode of the first child. If none exists then RESOK is "False".
	Use:
	<Xmlnode> := <Xmlnode>.FIRSTCHILD
GETELEMENTSBYTAGNAME	Returns a list of nodes (XMLNodes) that have the tagname <Name>. If there aren't any nodes with tagname <Name> then RESOK is "False".
	Use:
	<Xmlnodes> := <Xmlnode>.GETELEMENTSBYTAGNAME (<Name>):
	<Name>	Tagname to search for.

HASCHILDNODES	Returns a Boolean, "True" if there are child nodes or "False" if there are none existing.
	Use:
	<Xmlnode>.HASCHILDNODES
NAME	Returns a string that indicates the tag name of the specified node (readonly).
	Use:
	<Xmlnode>.NAME
NEXTSIBLING	Returns the next sibling (XMLNODE) for the node. If none exists then RESOK is "False".
	Use:
	<Xmlnode> := <Xmlnode>.NEXTSIBLING:
PARENTNODE	Returns the parent of the node (XMLNODE). If none exists then RESOK is "False".
	Use:
	<Xmlnode> := <Xmlnode>.PARENTNODE
PREVIOUSSIBLING	Returns the previous sibling for the node (XMLNODE). If none exists then RESOK is "False".
	Use:
	<Xmlnode> := <Xmlnode>.PREVIOUSSIBLING
SELECTNODES	Returns a list of nodes (XMLNODES) that meet the <Node Expression>. This is an XPATH expression. See the Microsoft DOM object documentation to learn more about the possibilities. If there isn't any node that meets the <Node Expression> then RESOK is "False". When the XML uses Namespaces, a Namespace manager must be defined and passed to this function as a parameter.
	Use:
	<Xmlnodes> := <Xmlnode>.SELECTNODES (<Node expression> [,<XmlNamespaceManager>])
	<Node expression>	Expression that indicates the node tag to search for.
	<XmlNamespaceManager>	XMLNamespace object that holds information about the Namespaces used in the XML.
	Example:MyNodes := MyNode.SELECTNODES('price')

SELECTSINGLENODE	Returns a single node (XMLNODE) that meets the <Node Expression>. This is an XPATH expression. See the Microsoft DOM object documentation to learn more about the possibilities. If there isn't any node that meets the <Node Expression> then RESOK is "False".
	Use:
	<Xmlnode> := <Xmlnode>.SELECTSINGLENODE (<Node expression>)
	<Node expression>	Expression that indicates the node tag to search for.

SETSCHEMALOCATION	Adds one or more schema locations to the node with a schema instance.
	Use:
	<Xmlnode>.SETSCHEMALOCATION(<SchemaLocation>, <SchemaInstance>)
	<SchemaLocation>	One or more Namespace URIs and Schema locations separated by spaces.
	<SchemaInstance>	The Schema Instance URI.
	Example: MyNode.SETSCHEMALOCATION( 'http://example.org/xml example.xsd http://example.org/xml example2.xsd', 'http://www.w3.org/2001/XMLSchema-instance')

VALUE	Returns or sets the value (String) of the specified node (writable).
	Use:
	<Xmlnode>.VALUE
	Example:MyNode.VALUE := MyNode.Value + ' extra value'

XMLNodes

The following function is available for the XMLNodes option:

Function	Description
LOOP FOR EACH	Creates a loop which sets <Xmlnode> to every node in <Xmlnodes> collection.
	Use:
	LOOP FOR EACH <Xmlnode> IN <Xmlnodes>

In the routine parameters, only a parameter of the type "XMLNode" may be passed.

XMLNamespaceManager

The following functions are available for the XMLNamespaceManager option:

Function	Description
ADDNAMESPACE	Add Namespace to the Namespace Manager.
	Use:
	<MyNsmgr>.AddNamespace(<Prefix>, <NamespaceUri>)
DEFAULTNAMESPACE	Set a Namespace Uri for the default Namespace.
	Use:
	<MyNsmgr>.DefaultNamespace
NAMETABLE	Holds XML attributes and element names necessary for the Namespace Manager.
	Use:
	<MyNsmgr>.NameTable
REMOVENAMESPACE	Removes Namespace from the Namespace Manager.
	Use:
	<MyNsmgr>.AddNamespace(<Prefix>, <NamespaceUri>)

For an example using the XMLNamespaceManager see: Consuming XML with Namespaces.