CatchXML()

Syntax

Result = CatchXML(#XML, *Address, Length [, Flags [, Encoding]])

Creates a new XML tree from XML data in the given memory area. The markup can be parsed in blocks by multiple calls to this function to allow parsing XML data while it arrives from the network for example. If #PB_Any is used as '#XML' parameter, the new XML tree number will be returned as 'Result'.

Parameters

'*Address' and 'Length' must specify a readable memory location. If 'Flags' is not specified, the memory location must contain all XML data. To parse XML in multiple blocks, the following flags can be used:

  #PB_XML_StreamStart: Start parsing the first block
  #PB_XML_StreamNext : Continue parsing with a new block
  #PB_XML_StreamEnd  : End parsing after this block

When calling this function with #PB_XML_StreamStart or #PB_XML_StreamEnd, the 'Length' parameter can be 0 to start/end a parsing operation without actually parsing more data.

Note that when parsing in blocks, all data already parsed is accessible in the XML tree even before a call with #PB_XML_StreamEnd is made.

The optional 'Encoding' parameter can be used to force the parser to use a specific encoding. (This overwrites the encoding set in the XML declaration!) Possible values are #PB_Ascii, #PB_Unicode or #PB_UTF8. This parameter should be used when the document does not have an XML declaration, or the encoding information is provided outside of the XML document, for example through a mime type header in a communication protocol.

Return value

This function only returns 0 on memory errors or invalid Flags. To check for parser errors XMLStatus() should be used. In case of a parsing error, all data parsed before the error is accessible in the XML tree.

Supported OS

All