--- title: "XML" canonical: "https://docs.cuesystem.com/space/CVCHELP/512983459/XML" format: markdown --- > Macro (toc) --- Functions for parsing XML text are divided into classes built-in into the firmware. The first class to be used is the class _XmlParser. This class parses XML text and creates system data for it. The second class necessary is _XmlElement. It represents XML element with names, attributes, and content. _XmlContentItem class represents one content item of the XML element. It can be whitespace value, text data value, name referenced value, CDATA value, and/or subelement value. _XmlAttribute class represents one attribute of an XML element.  # **_XmlParser class** This class represents an XML parser. It includes functions necessary for parsing XML text.  # Create This function parses XML text and gets the result of parsing. The text must be complete before using this function. **The function does not create an internal copy of the text. The text must be in the same controller and must not be changed after using Create and before using Destroy**.  #### Syntax  ```visualbasic Public Function Create(xmltext As AddressOf Text) As Boolean ``` #### xmltext  It is the address of the text with XML data. XML data can be read from the IP stream or taken from the file.  The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 190 | Unexpected end of the XML text | XML text is not complete. | | 192 | XML text syntactically invalid. | XML text does match the XML standard specification. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | | 149 | Not enough memory. | The system does not have enough memory to complete the action required. | | 2147483643 | Not enough system resources. | Too much XML parsers in use. | ```visualbasic Var tXmlData As Text  :=   ""  ""    ""       "Anna"       "Smith"    ""    ""       "John"       "Smith"     ""  ""  Process Autoexec()  PaseXMLText(tXmlData)  End Process  Function PaseXMLText(txmlData As Text) As Boolean  Var parser As _XmlParser  Var rootelement As _XmlElement  Var personelement As _XmlElement   Var tmpelement As _XmlElement   Var personattribute As _XmlAttribute  Var valuetext As Text[100]  Var i As Long  Var count As Long   If Not parser.Create( tXmlData) Then  DebugPrintFormat( "XML Parse Error: {N}", GetLastError())  Return Value False  End If  If parser.GetRootElement(rootelement) And rootelement.GetContentItemCount(count) Then       For i:= 1 To count      If rootelement.FindSubElement("person",personelement,i) Then              If personelement.FindAttribute("ID",personattribute) And personattribute.GetValue(valuetext) Then       DebugPrintFormat("person ID =  {t}",valuetext)  End If   If personelement.FindSubElement("firstname",tmpelement) And tmpelement.GetValue(valuetext) Then     DebugPrintFormat(" firstname =  {t}",valuetext)  End If  If personelement.FindSubElement("lastname",tmpelement) And tmpelement.GetValue(valuetext) Then           DebugPrintFormat(" lastname =  {t}",valuetext)  End If  End If  End For   End If  parser.Destroy()  Return Value True  End Function ``` It prints to the debug window:  ```visualbasic person ID =  1  firstname =  Anna  lastname =  Smith  person ID =  2  firstname =  John  lastname =  Smith ``` # GetRootElement This function looks for the root XML element. Before using this function, the programmer has to use the function Create.  #### Syntax  ```visualbasic Public Function GetRootElement(ByRef xmlelement As _XmlElement) As Boolean ``` #### xmlelement  This output value xmlelement will be initialized and then it can be used.  The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function Create was not used before or the data were destroyed by the function Destroy. | | 199 | XML element not found. | The root element does not exist. The function Create returned false probably. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | #### Example  ```visualbasic Function MyXmlParse(xml As Text) As Boolean  Var parser As _XmlParser  Var e As _XmlElement  if not parser.Create(xml) then  return value false   end if  if not parser.GetRootElement(e) then  return value false   end if  // ... next activities  return value true  End Function ``` # Destroy  This function destroys all internal XML data of the _XmlParser instance. After using this function, the programmer must not use other functions but Create.  > ℹ️ This function is a class destructor and the system calls it automatically when an instance of the _XMLParser class passes out of scope. Therefore, it is not necessary to call it explicitly. #### Syntax  ```visualbasic Public Function Destroy() ``` # **_XmlElement class** This class has to be used for obtaining values of the XML element. _XmlElement class instance can be obtained by _XmlParser.GetRootElement or XmlContentItem.GetElement or XmlContentItem.FindSubElement.  # GetName This function fills the name of the element into the output parameter name.  ```visualbasic Public Function GetName(ByRef name As Text) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 191 | Destination buffer too short. | The output parameter name is declared too short. The name of the element is longer. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetAttributeCount GetAttributeCount function returns the number of attributes of the element in the output parameter *attribcount.*  ```visualbasic Public Function GetAttributeCount(ByRef attribcount As Long) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetAttribute GetAttribute function returns the single attribute of the XML element in the output parameter dstattribute. The parameter attributeindex has to be between 1 and _XmlElement.GetAttributeCount.  ```visualbasic Public Function GetAttribute( attributeindex As Long, ByRef dstattribute As _XmlAttribute) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 200 | Attribute has not been found. | The required attribute does not exist. Maybe the *attributeindex* is invalid. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # FindAttribute FindAttribute function returns the single attribute of the XML element in the output parameter dstattribute. The parameter attributename has to be a valid name. The name is case-sensitive because of the XML standard specification.  ```visualbasic Public Function FindAttribute( attributename As Text, ByRef dstattribute As _XmlAttribute) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 200 | Attribute has not been found. | The required attribute does not exist. Maybe the *name* is invalid. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetContentItemCount The function returns the count of element subitems in the output parameter *contentitemcount*.  ```visualbasic Public Function GetContentItemCount(ByRef contentitemcount As Long) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetContentItem The function returns the single content item of the XML element. This function can be used for detailed operations on the element subitems. The subitem can be of different type (see _XmlContentItem.GetType).  ```visualbasic Public Function GetContentItem( itemindex As Long, ByRef contentitem As _XmlContentItem) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # FindSubElement FindSubElement function can be used, if the programmer can find the subelement of the specified name. The parameter *elementindex* specifies the order number of the subelement with the same name.  ```visualbasic Public Function FindSubElement( elementname As Text, ByRef xmlelement As _XmlElement, Optional elementindex As Long := 1) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetValue This function returns the summarized value of all content items of the element in the output parameter *dstvalue*. If the element contains subelements (not only values), then the function returns false with an error subelement found. The *dstvalue* contains all values found. It does not contain the value of the subelement.  ```visualbasic Public Function GetValue(ByRef dstvalue As Text) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 202 | Subelement found. | The element contains subelements - not only simple values. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # **_XmlAttribute class** This class has to be used for obtaining values of the XML element attributes. _XmlAttribute class instance can be obtained by _XmlElement.GetAttribute or _XmlElement.FindAttribute.  # GetName Function GetName returns the name of the XML attribute in the output parameter *attributename*.  ```visualbasic Public Function GetName(ByRef attributename As Text) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 191 | Destination buffer too short. | The declared length of the *attributename* parameter is too short. | | 200 | Attribute not found. | The _XmlAttribute class was used after destroying the _XmlParser. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetValue Function GetValue returns the value of the XML attribute in the output parameter *attributevalue*.  ```visualbasic Public Function GetName(ByRef attributevalue As Text) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 191 | Destination buffer too short. | The declared length of the *attributevalue* parameter is too short. | | 200 | Attribute not found. | The _XmlAttribute class was used after destroying the _XmlParser. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 199 | Element not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # **_XmlContentItem class** This class represents the individual single subitem of the XML element. By the XML standard, the element can have five different types of subitems:  - Whitespace value, - Reference value, - Char data value, - Cdata value, - Element value. The first of them can be represented as a text value. The last is the standard XML element with attributes and subitems. The valid instance of the _XmlContentItem class has to be taken from the function _XmlElement.GetContentItem.  # GetType The function returns the type of the content item in the output parameter *contenttype*. The types are descripted in the table below. The types can be tested with help of predefined constants  (see table).  ```visualbasic Public Function GetType(ByRef contenttype As Long) As Boolean ``` #### Table of types  | | | | | --- | --- | --- | | Reference | _XMLCTYPE_REFERENCE | 1 | | Whitespace | _XMLCTYPE_WHITESPACE | 2 | | Char data | _XMLCTYPE_CHARDATA | 3 | | Cdata | _XMLCTYPE_CDSECT | 4 | | Element | _XMLCTYPE_ELEMENT | 5 | The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 198 | Content item not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetElement The function can be used, if the content item type is _XMLCTYPE_ELEMENT. Otherwise, it returns false. If the function succeeds, then the *xmlelement* parameter is valid and can be used.  ```visualbasic Public Function GetElement(ByRef xmlelement As _XmlElement) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers  | | | | | --- | --- | --- | | 201 | Content item type does not match. | The content item type is not _XMLCTYPE_ELEMENT. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 198 | Content item not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. | # GetValue The function returns the text value of the data item. The type of the item can not be _XMLCTYPE_ELEMENT.  ```visualbasic Public Function GetValue(ByRef itemvalue As Text) As Boolean ``` The function returns true on success. If any error appears, then the function returns false and the error number can be found using GetLastError().  #### GetLasError error numbers* * | | | | | --- | --- | --- | | 191 | Destination buffer too short. | The declared length of the *itemvalue* parameter is too short. | | 201 | Content item type does not match. | The content item type is not _XMLCTYPE_ELEMENT. | | 197 | Parser data not found. | The function _XmlParser.Create was not used before or the data were destroyed by the function Destroy. | | 198 | Content item not found. | _XmlElement class data are invalid. Maybe the _XmlParser class used Destroy or does not exist at the moment or the element was not initialized. | | 2147483645 | Unexpected system error. | The function failed in unexpected situation. |