XML_NEXT
| Argument | Enumeration | Purpose |
|---|---|---|
| handle | XML handle | |
| SYM(name$) | Symbol of element name | |
| SYM(value$) | Symbol of element value | |
| SYM(attr$()) | Symbol of elements array | |
| SYM(values$()) | Symbol of values array | |
| status | KDB_ERROR_ENUM | Return status |
| level | Returned indent level | |
| nodetype | Returned node type |
XML_NEXT
This function returns the next element for an XML tree opened on the handle by XML_OPEN or XML_PARSE_BUFFER. The tree is traversed from the top with the parser descending each element to its maximum depth before returning the next element. On each call to this function the next element is selected and the name and value are returned. These scalar string variables will be redimensioned to the exact size of the parsed data. Some elements may have attributes and their values are also returned in arrays which are dynamically dimensioned by the function to a suitable size. Passing zero for any of these SYM() arguments is allowed.
Irrespective of the original document encoding, the strings returned by XML_NEXT are always encoded as UTF-8.
When the last element of the tree has been reached, the next call will return a status of 2.
The level of the element is available in the optional level argument with the root node having a level of zero. Monitoring the level can allow you to see how elements are nested without having to check for closing tags.
The optional nodetype argument can be used to see the various components of the document. By default only opening tags, with a nodetype value of 1, are returned but XML_OPTIONS can be used to expose other components which are distinguished by the value of nodetype.
| nodetype | component |
|---|---|
| 1 | Opening element tags. Returns tag name in name$, the element value, if any, in value$ and any attributes in the arrays attr$() and values$(). |
| 2 | Closing element tags. Returns tag name. |
| 3 | Comment. Returns blank in name$ and the comment text in value$. |
| 4 | Processing instruction. Returns the target in name$ and the data in value$. |
The status code values returned are the same as those returned by database routines. A status code of 40 implies a syntax error in the XML and further information about the nature and position of the error can be found from XML_ERROR. The XML specification calls for the parser to abandon processing after encountering the first error. Because an internal tree is built by the parser on the first call to XML_NEXT rather than at the point where the handle was allocated, parsing errors are reported by that first call and the application will never see a partial tree.