XML writing and parsing

XML documents can be managed from the IEC application as a tree of “XML tags”. Each XML tag is represented by:

-          a tag name

-          a list of attributes (name=value)

-          a contents (raw text)

-          a list of child tags

A whole XML document is handled as its main tag.

XML functions are originally designed for working with text buffers. However, some additional functions have been added for dealing with XML files on disk as it may be helpful in other applications.

Important notes:

Below are the functions and function blocks for handing XML documents:

Memory management / Miscellaneous:

XmlManager: main gatherer of XML data in memory

XmlLastError: get detailed error report about last call

Reading/writing documents:

XmlNewDoc: Create an empty XML document

XmlFreeDoc: Release an XML document from memory

XmlParseDocTxb: Parse an XML document from text buffer

XmlParseDocFile: Parse an XML document form file

XmlWriteDocTxb: Format XML data to text buffer

XmlWriteDocFile: Format XML data to file

Exploring an XML document:

XmlGetTagName: Get name of an XML tag

XmlCheckTagName: Test the name of an XML tag

XmlGetTagCont: Get tag contents as STRING

XmlGetTagContT: Get tag contents as text buffer

XmlGetTagAttrib: Get tag attribute

XmlFirstChild: Start enumerating child tags

XmlNextChild: Enumerate child tags

Building an XML document:

XmlSetTagAttrib: Set tag attribute

XmlSetTagCont: Set tag contents with STRING

XmlSetTagContT: Set tag contents with text buffer

XmlAddChild: Add a child tag

Exchanging variables using their name:

XmlGetSybValue: Get variable value using its symbol

XmlSetSybValue: Set variable value using its symbol

Description:

This function block is used for managing the memory allocated for XML tags and documents. It takes care of releasing the corresponding memory when the application stops, and can be used for tracking memory leaks. There must be one and only one instance of this block declared in the IEC application in order to use any other Xml... function.

Outputs:

See also...

Description:

All XML functions and blocks simply return a boolean information as a return value. This function can be called after any other function giving a FALSE return. It gives a detailed error code about the last detected error.

Outputs:

Below are possible error codes:

1   Invalid instance of XMLManager (should be only one)
2   Manager already open - should be only one instance declared
3   Manager not open - no instance of XmlManager declared
4   Invalid handle
5   Too many tags allocated
6   Invalid handle of a text buffer (or no instance of TxbManager declared)
7   Invalid XML file or XML syntax error
8   Cannot read file
9   Cannot write file
 

See also...

Description:

This function allocates a new XML document, initially filled with one empty root tag. The application is responsible for releasing the allocated memory by calling the XmlFreeDoc function.

Inputs:

Outputs:

See also...

Description:

This function releases the memory allocated for an XML document. It releases the specified tag and all its child tags. This function can also be used to delete a child tag and keep its parent tag in memory.

Inputs:

Outputs:

See also...

Description:

This function parses the XML text contained in a text buffer and allocates a new XML document to store it. The application is responsible for releasing the allocated memory by calling the XmlFreeDoc function.

Important: XML parsing and witing functions support only 8 bit encoding features. This can be UTF8 or ANSI (ISO-8859-1) encoding. Some additional functions will be provided for conversion between UTF8 and ANSI formats.

Inputs:

Outputs:

See also...

Description:

This function parses the XML text contained in a file and allocates a new XML document to store it. The application is responsible for releasing the allocated memory by calling the XmlFreeDoc function.

Important: XML parsing and witing functions support only 8 bit encoding features. This can be UTF8 or ANSI (ISO-8859-1) encoding. Some additional functions will be provided for conversion between UTF8 and ANSI formats.

Inputs:

Outputs:

See also...

Description:

This function format an XML document to a text buffer. It does not releases the memory allocated for the XML document.

Important: XML parsing and witing functions support only 8 bit encoding features. This can be UTF8 or ANSI (ISO-8859-1) encoding. Some additional functions will be provided for conversion between UTF8 and ANSI formats.

Inputs:

Outputs:

See also...

Description:

This function format an XML document to a file. It does not releases the memory allocated for the XML document.

Important: XML parsing and writing functions support only 8 bit encoding features. This can be UTF8 or ANSI (ISO-8859-1) encoding. Some additional functions will be provided for conversion between UTF8 and ANSI formats.

Inputs:

Outputs:

See also...

Description:

This function returns the name of an XML tag.

Inputs:

Outputs:

See also...

Description:

This function returns TRUE if the specified tag has the specified name. This function makes case insensitive comparison of tag manes.

Inputs:

Outputs:

See also...

Description:

This function copies the contents of an XML tag to a variable. The specified variable can have any data type.

Inputs:

Outputs:

See also...

Description:

This function copies the contents of an XML tag to a text buffer. The text buffer is allocated by the function, and must be released by the application after use.

Inputs:

Outputs:

See also...

Description:

This function copies the contents of an XML attribute to a variable. The specified variable can have any data type.

Inputs:

Outputs:

See also...

Description:

This function returns the handle of the first child tag having the specified name. If “szTag” is empty, then the first child tag is returned whatever its name is.

Inputs:

Outputs:

Typical use in ST:

hChild := XmlFirstChild (hParentTag, 'TagName');

while hChild <> 0 do

   (* explore the tag *)

   hChild := XmlNextChild (hParentTag, hChild, 'TagName');

end_while;

See also...

Description:

This function returns the handle of the next child tag having the specified name. If “szTag” is empty, then the next child tag is returned whatever its name is.

Inputs:

Outputs:

Typical use in ST:

hChild := XmlFirstChild (hParentTag, 'TagName');

while hChild <> 0 do

   (* explore the tag *)

   hChild := XmlNextChild (hParentTag, hChild, 'TagName');

end_while;

See also...

Description:

This function copies the value of a variable to an XML attribute. The specified variable can have any data type.

Inputs:

Outputs:

See also...

Description:

This function copies the value of a variable to the contents of an XML tag. The specified variable can have any data type.

Inputs:

Outputs:

See also...

Description:

This function copies a text buffer to the contents of an XML tag. The text buffer is allocated by the application, and must be released by the application after use.

Inputs:

Outputs:

See also...

Description:

This function adds a new child tag to an XML tag, with the specified tag name.

Inputs:

Outputs:

See also...

Description:

This function copies the value of the variable having the symbol specified in “szSyb” to the output string. It assumes that the symbol of the variable has been embedded in the runtime application.

This function enables the automation of data exchange between XML data and the runtime. For example, you can find the symbol of a variable in a tag attribute and update the value in another one.

Inputs:

Outputs:

See also...

Description:

This function copies the value of the variable having the symbol specified in “szSyb” to the output string. It assumes that the symbol of the variable has been embedded in the runtime application.

This function enables the automation of data exchange between XML data and the runtime. For example, you can find the symbol of a variable in a tag attribute and the value in another one.

Inputs:

Outputs:

See also...