Kernel 8.0 APIs Banner
Office of Information and Technology (OIT) Banner
[skip navigation]

EN^MXMLPRSE(): XML—Event Driven API

Reference Type: Supported, Category: XML Parser (VistA), ICR#: 4149

Description

The EN^MXMLPRSE API is an event-driven interface that is based on the well-established Simple API for XML (SAX) interface employed by many XML parsers. This API has a single method.

In this implementation, a client application provides a special handler for each parsing event of interest. When the client invokes the parser, it conveys not only the document to be parsed, but also the entry points for each of its event handlers. As the parser progresses through the document, it invokes the client’s handlers for each parsing event for which a handler has been registered.

Format

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

Input Parameters

doc:

(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" ...

Or:

  • ^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>

REF: For the types of supported events and their required parameters, see the "Details" section.
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 Parameters 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)—Warning.

    • 1—Validation error.

    • 2—Conformance error.

  • ERR("MSG")—Brief text description of the error.

  • ERR("ARG")—Token value the triggered the error (optional).

  • ERR("LIN")—Number of the line being processed when the error occurred.

  • ERR("POS")—Character position within the line where the error occurred.

  • ERR("XML")—Original document text of the line where the error occurred.

Example

This is a simple example of how to use the VistA XML Parser with an XML document (file). The XML file contains a parent node named BOOKS. Nested within that parent node are child nodes named TITLE and AUTHOR.

Remember the following:

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.

  1. Create an XML file:

    VistA XML Parser Use—Example: Create XML file

    ^TMP($J,1) = 
^TMP($J,2) = 
^TMP($J,3) = 
^TMP($J,4) = Design Patterns
^TMP($J,5) = Author1
^TMP($J,6) = Author2
^TMP($J,7) = Author3
^TMP($J,8) = Author4
^TMP($J,9) =


  2. Invoke simple API for XML (SAX) interface:

    VistA XML Parser Use—Example: Simple API for XML (SAX) Interface

    D EN^MXMLTEST($NA(^TMP($J)),”V”)


  3. Check Document Object Model (DOM) interface:

    VistA XML Parser Use—Example: Check Document Object Model (DOM) Interface

    >S HDL=$$EN^MXMLDOM($NA(^TMP($J)))
 
>W $$NAME^MXMLDOM(HDL,1)
BOOK
 
>S CHD=$$CHILD^MXMLDOM(HDL,1)
 
>W $$NAME^MXMLDOM(HDL,CHD)
TITLE

 
>W $$TEXT^MXMLDOM(HDL,CHD,$NA(VV))
1

>ZW VV
VV(1)=Design Patterns


  4. List all sibling nodes:

    VistA XML Parser Use—Example: List All Sibling Nodes

    >S CHD=$$CHILD^MXMLDOM(HDL,1)

>S SIB=CHD

>F  S SIB=$$SIBLING^MXMLDOM(HDL,SIB) Q:SIB’>0  W !,SIB,?4,$$NAME^MXMLDOM(HDL,SIB)
3   AUTHOR
4   AUTHOR
5   AUTHOR
6   AUTHOR
>