Kernel APIs: EN^MXMLPRSE

EN^MXMLPRSE(): XML—Event Driven API

Reference Type: Supported, Category: XML, Integration Agreement: 4149

Description

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.

Format

  EN^MXMLPRSE(doc[,cbk][,opt])

(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:

^XYZ(1,0) = "LINE 1"

^XYZ(2,0) = "LINE 2" ...

^XYZ(1) = "LINE 1"

^XYZ(2) = "LINE 2" ...

cbk:

(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:

     CBK(<event type>) = <entry point>

The entry point must reference a valid entry point in an existing M routine and should be of the format tag^routine. The entry should not contain any formal parameter references. The application developer is responsible for ensuring that the actual entry point contains the appropriate number of formal parameters for the event type. For example, client application might register its STARTELEMENT event handler as follows:

     CBK("STARTELEMENT") = "STELE^CLNT"

The actual entry point in the CLNT routine must include two formal parameters as in the following example:

     STELE(ELE,ATR) <handler code>

For the types of supported events and their required parameters, see the "Details" topic.

opt:

(optional) This string is a list of option flags that control parser behavior. Recognized option flags are:

W—Do not report warnings to the client.
V—Validate the document. If not specified, the parser only checks for conformance.
1—Terminate parsing on encountering a validation error. (By default, the parser terminates only when a conformance error is encountered.)
0—Terminate parsing on encountering a warning.

Output

returns:

Returns the XML parsed string.

Details

The VistA XML Parser recognizes the following event types:

Event Types	Parameter(s)	Description
STARTDOCUMENT	None	Notifies the client that document parsing has commenced.
ENDDOCUMENT	None	Notifies the client that document parsing has completed.
DOCTYPE	ROOT PUBID SYSID	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.
STARTELEMENT	NAME ATTRLIST	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.
PI	TARGET TEXT	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.
EXTERNAL	SYSID PUBID GLOBAL	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.
NOTATION	NAME SYSID PUBIC	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.
ERROR	ERR	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. ERR("MSG") = Brief text description of the error. ERR("ARG") = The token value the triggered the error (optional). ERR("LIN") = The number of the line being processed when the error occurred. ERR("POS") = The character position within the line where the error occurred. ERR("XML") = The original document text of the line where the error occurred.

Example

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.

VA (Internet) / VA (Intranet) / OI / HSD&D / Site Map / Terms of Use / VA Privacy Policy / Accessibility