Reference Type: Supported, Category: XML, Integration Agreement: 4149
This API is based on the well-established Simple API for XML (SAX) interface employed by many XML parsers. This API has a single method.
(required) This string is either a closed reference to a global root containing the document or a filename and path reference identifying the document on the host system. If a global root is passed, the document either must be stored in standard VA FileMan word-processing format or may occur in sequentially numbered nodes below the root node. Thus, if the global reference is "^XYZ", the global must be of one of the following formats:
(optional) This is a local array, passed by reference that contains a
list of parse events and the entry points for the handlers of those
events. The format for each entry is:
(optional) This string is a list of option flags that control parser behavior. Recognized option flags are:
Returns the XML parsed string.
The VistA XML Parser recognizes the following event types:
|STARTDOCUMENT||None||Notifies the client that document parsing has commenced.|
|ENDDOCUMENT||None||Notifies the client that document parsing has completed.|
|Notifies the client that a DOCTYPE declaration has been encountered. The name of the document root is given by ROOT. The public and system identifiers of the external document type definition are given by PUBID and SYSID, respectively.|
An element (tag) has been encountered. The name of the
element is given in NAME.
The list of attributes and their values is provided in the local array
ATTRLST in the format:
ATTRLST(<name>) = <value>
|ENDELEMENT||NAME||A closing element (tag) has been encountered. The name of the element is given in NAME.|
|CHARACTERS||TEXT||Non-markup content has been encountered. TEXT contains the text. Line breaks within the original document are represented as carriage return/line feed character sequences. The parser does not necessarily pass an entire line of the original document to the client with each event of this type.|
|The parser has encountered a processing instruction. TARGET is the target application for the processing instruction. TEXT is a local array containing the parameters for the instruction.|
|The parser has encountered an external entity reference whose system and public identifiers are given by SYSID and PUBID, respectively. If the event handler elects to retrieve the entity rather than allowing the parser to do so, it should pass the global root of the retrieved entity in the GLOBAL parameter. If the event handler wishes to suppress retrieval of the entity altogether, it should set both SYSID and PUBID to null.|
|The parser has encountered a notation declaration. The notation name is given by NAME. The system and public identifiers associated with the notation are given by SYSID and PUBIC, respectively.|
|COMMENT||TEXT||The parser has encountered a comment. TEXT is the text of the comment.|
The parser has encountered an error during the processing of a document. ERR is a local array containing information about the error. The format is:
ERR("SEV") = Severity of the error where zero (0) is a warning, 1 is a validation error, and 2 is a conformance error.
A sample client of the event-driven API is provided in the routine MXMLTEST. This routine has an entry point EN(DOC,OPT), where DOC and OPT are the same parameters as described above in for the parser entry point. This sample application simply prints a summary of the parsing events as they occur.
August 26, 2011