TXmlDocument() > Methods for XML data manipulation

oTXmlDocument:read()

Reads an XML file or string.

Syntax

:read( [<nFileHandle>|<cXmlString>], [<nStyle>] ) --> self

Arguments

<nFileHandle>

This is a file handle of an XML file to read. It is returned from function FOpen().

<cXmlString>

Instead of a file handle, an XML formatted character string can be passed. If the first parameter is omitted, the object has no XML data, but can be used to add XML nodes and create a new XML file.

<nStyle>

This parameter instructs the TXMlDocument object how to read an XML file and/or how to write XML nodes into a file. #define constants listed in Hbxml.ch are used to specify <nStyle>:

Constants for XML object creation

Constant	Value	Description
HBXML_STYLE_INDENT	1	Indents XML nodes with one space
HBXML_STYLE_TAB	2	Indents XML nodes with tabs
HBXML_STYLE_THREESPACES	4	Indents XML nodes with three spaces
HBXML_STYLE_NOESCAPE	8	Reads and creates unescaped characters
		in data sections

Description

Method :read() receives the same parameters as the :new() method and instructs an existing TXmlDocument object to discard the previously created XML tree and build a new one from the file handle or XML string. When the XML data is sucessfully parsed, instance variable :nError is set to zero.

Note:  when the style HBXML_STYLE_NOESCAPE is set, the textual content enclosed in an opening and closing XML tag is scanned for characters that normally must be escaped in XML. This can lead to a considerable longer time for reading the XML data.

The characters to be escaped are single and double quotes ('"), ampersand (&), and angled brackets (<>). If such characters exist in textual content and are not escaped, a parsing error is generated, unless HBXML_STYLE_NOESCAPE is used.