-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathen-mxmlprse.html
executable file
·625 lines (610 loc) · 20.9 KB
/
en-mxmlprse.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
<HTML>
<HEAD>
<!--VA Office of Information and Technology (OIT)-->
<!--Oakland OIFO-->
<!-- START: META DATA -->
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="language"
content="en">
<meta name="creator"
content="Department of Veterans Affairs (VA), Office of Information and Technology (OIT), VistA Infrastructure (VI)">
<meta name="subject"
content="Kernel APIs: EN^MXMLPRSE">
<meta name="keywords"
content="VistA Infrastructure,VI,Infrastructure,Infrastructure and Seucurity Services,Information Infrastructure Service,OIT,OI&T,ISS,IIS,VISTA,kernel,programmer,developer,programmer manual,apis,application programming interface,application,programming,interface,entry point,EN^MXMLPRSE,EN,MXMLPRSE,xml,extensible markup language,supported">
<meta name="description"
content="Kernel APIs: EN^MXMLPRSE">
<meta name="datecreated"
content="20010101">
<meta name="datereviewed"
content="20180813">
<meta name="type"
content="Homepage">
<!-- END: META DATA -->
<title>Kernel APIs: EN^MXMLPRSE</title>
<LINK REL="StyleSheet"
TYPE="text/css"
HREF="common/developer.css">
</HEAD>
<BODY>
<header>
<!--Start Title Banner (image)-->
<TABLE BORDER="0"
WIDTH="100%"
CELLSPACING="3"
CELLPADDING="3"
SUMMARY="This table is for formatting purposes only">
<TR>
<TD VALIGN="top"
ALIGN="left">
<IMG SRC="images/kernel_heading_APIs.gif"
ALT="Kernel 8.0 APIs Banner"
BORDER="0">
<BR>
<IMG SRC="images/oitbanner.gif"
ALT="Office of Information and Technology (OIT) Banner"
BORDER="0">
</TD>
</TR>
</TABLE>
<A HREF="#navskip">
<IMG SRC="images/clr_pxl.gif"
ALT="[skip navigation]"
WIDTH="25"
HEIGHT="1"
BORDER="0"></A>
<!--End Title Banner (image)-->
</header>
<!-- Start Content -->
<H3><A NAME="navskip">EN^MXMLPRSE</A>(): XML—Event Driven API</H3>
<P><B>Reference Type:</B> Supported, <B>Category:</B> XML Parser (VistA),
<B>ICR#:</B> 4149</P>
<H4><A NAME="description">Description</A></H4>
<P>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.</P>
<p>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.</p>
<H4><A NAME="format">Format</A></H4>
<PRE> EN^MXMLPRSE(doc[,cbk][,opt])</PRE>
<H4><A NAME="input_parameters">Input Parameters</A></H4>
<TABLE BORDER="1"
CELLPADDING="5"
BGCOLOR="#F1F2F3"
BORDERCOLORLIGHT="#F1F2F3"
BORDERCOLORDARK="#808080"
WIDTH="100%">
<TR>
<TD VALIGN="TOP"
WIDTH="15%">
<B>doc:</B>
</TD>
<TD VALIGN="TOP"
WIDTH="85%">
<P>(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 <em>must</em> 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
"<strong>^XYZ</strong>", the global <em>must</em> be of one of the following
formats:</P>
<UL>
<LI>
<strong>^XYZ(1,0) = "LINE 1"
<BR>
<BR>
^XYZ(2,0) = "LINE 2" ...
</strong>
</LI>
</UL>
<P>Or:</P>
<UL>
<LI>
<strong>^XYZ(1) = "LINE 1"
<BR>
<BR>
^XYZ(2) = "LINE 2" ...
</strong>
</LI>
</UL>
</TD>
</TR>
<TR>
<TD VALIGN="TOP"
WIDTH="15%">
<B>cbk:</B>
</TD>
<TD VALIGN="TOP"
WIDTH="85%">
<P>(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:</P>
<PRE>
CBK(<<I>event type</I>>) = <<I>entry point</I>></PRE>
<p>The entry point <i>must</i> reference a valid entry point in an existing M
routine and should be of the format <I>tag^routine</I>. The entry should
<i>not</i> 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:</p>
<PRE>
CBK("STARTELEMENT") = "STELE^CLNT"
</PRE>
<p>The actual entry point in the <strong>CLNT</strong> routine <em>must</em> include two formal
parameters as in the following example:<p>
<PRE>
STELE(ELE,ATR) <<i>handler code</i>>
</PRE>
<p><b>REF:</b> For the types of supported events and their required parameters, see
the "<A HREF="#details"
CLASS="BODYLINK"
TITLE="Details">Details</A>"
section.</p>
</TD>
</TR>
<TR>
<TD VALIGN="TOP"
WIDTH="15%">
<B>opt:</B>
</TD>
<TD VALIGN="TOP"
WIDTH="85%">
<P>(optional) This string is a list of option flags that control parser
behavior. Recognized option flags are:</P>
<UL>
<LI>
<b>W—</b>Do <i>not</i> report warnings to the client.
<BR>
<BR>
</LI>
<LI>
<b>V—</b>Validate the document. If <i>not</i> specified, the parser
only checks for conformance.
<BR>
<BR>
</LI>
<LI>
<b>1—</b>Terminate parsing on encountering a validation error. (By
default, the parser terminates only when a conformance error is
encountered.)
<BR>
<BR>
</LI>
<LI>
<b>0—</b>Terminate parsing on encountering a warning.
</LI>
</UL>
</TD>
</TR>
</TABLE>
<H4><A NAME="output">Output</A></H4>
<TABLE BORDER="1"
CELLPADDING="5"
BGCOLOR="#F1F2F3"
BORDERCOLORLIGHT="#F1F2F3"
BORDERCOLORDARK="#808080"
WIDTH="100%">
<TR>
<TD VALIGN="TOP"
WIDTH="15%">
<B>returns:</B>
</TD>
<TD VALIGN="TOP"
WIDTH="85%">
<P>Returns the XML parsed string.</P>
</TD>
</TR>
</TABLE>
<H4><A NAME="details">Details</A></H4>
<P>The VistA XML Parser recognizes the following event types:</P>
<TABLE BORDER="1"
CELLPADDING="5"
BGCOLOR="#F1F2F3"
BORDERCOLORLIGHT="#F1F2F3"
BORDERCOLORDARK="#808080"
WIDTH="100%">
<TR>
<TH WIDTH="10%"
align="left">
Event Types
</TH>
<TH WIDTH="10%"
align="left">
Parameters
</TH>
<TH WIDTH="80%"
align="left">
Description
</TH>
</TR>
<TR>
<TD VALIGN=TOP>
<B>STARTDOCUMENT</B>
</TD>
<TD VALIGN=TOP>
None
</TD>
<TD VALIGN=TOP>
Notifies the client that document parsing has commenced.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>ENDDOCUMENT</B>
</TD>
<TD VALIGN=TOP>
None
</TD>
<TD VALIGN=TOP>
Notifies the client that document parsing has completed.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>DOCTYPE</B>
</TD>
<TD VALIGN=TOP>
ROOT
<BR>
PUBID
<BR>
SYSID
</TD>
<TD VALIGN=TOP>
Notifies the client that a <strong>DOCTYPE</strong> declaration has been
encountered. The name of the document root is given by <strong>ROOT</strong>. The public and system identifiers of the external document type
definition are given by <strong>PUBID</strong>
and <strong>SYSID</strong>, respectively.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>STARTELEMENT</B>
</TD>
<TD VALIGN=TOP>
NAME
<BR>
ATTRLIST
</TD>
<TD VALIGN=TOP>
An element (tag) has been encountered. The name of the
element is given in <strong>NAME</strong>.
The list of attributes and their values is provided in the local array
<strong>ATTRLST</strong> in the format:
<BR>
<BR>
<strong>ATTRLST(</strong><em><strong><name></strong></em><strong>) =
</strong><em><strong><value></strong></em>
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>ENDELEMENT</B>
</TD>
<TD VALIGN=TOP>
NAME
</TD>
<TD VALIGN=TOP>
A closing element (tag) has been encountered. The name
of the element is given in <strong>NAME</strong>.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>CHARACTERS</B>
</TD>
<TD VALIGN=TOP>
TEXT
</TD>
<TD VALIGN=TOP>
<em>Non</em>-markup content has been encountered. <strong>TEXT</strong>
contains the text. Line breaks within the original document are
represented as carriage return/line feed character sequences. The
parser does <i>not</i> necessarily pass an entire line of the original
document to the client with each event of this type.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>PI</B>
</TD>
<TD VALIGN=TOP>
TARGET
<BR>
TEXT
</TD>
<TD VALIGN=TOP>
The parser has encountered a processing
instruction. <strong>TARGET</strong> is the target application for the processing instruction.
<strong>TEXT</strong> is a local array containing the parameters for the instruction.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>EXTERNAL</B>
</TD>
<TD VALIGN=TOP>
SYSID
<BR>
PUBID
<BR>
GLOBAL
</TD>
<TD VALIGN=TOP>
The parser has encountered an external entity
reference whose system and public identifiers are given by <strong>SYSID</strong> and <strong>PUBID</strong>,
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 <strong>GLOBAL</strong> parameter. If the event handler wishes to suppress retrieval
of the entity altogether, it should set both <strong>SYSID</strong>
and <strong>PUBID</strong> to <strong>NULL</strong>.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>NOTATION</B>
</TD>
<TD VALIGN=TOP>
NAME
<BR>
SYSID
<BR>
PUBIC
</TD>
<TD VALIGN=TOP>
The parser has encountered a notation
declaration. The notation name is given by <strong>NAME</strong>.
The system and public identifiers associated with the notation are
given by <strong>SYSID</strong> and <strong>PUBIC</strong>, respectively.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>COMMENT</B>
</TD>
<TD VALIGN=TOP>
TEXT
</TD>
<TD VALIGN=TOP>
The parser has encountered a comment. <strong>TEXT</strong>
is the text of the comment.
</TD>
</TR>
<TR>
<TD VALIGN=TOP>
<B>ERROR</B>
</TD>
<TD VALIGN=TOP>
ERR
</TD>
<TD VALIGN=TOP>
<P>The parser has encountered an error during the processing of a
document. <strong>ERR</strong> is a local
array containing information about the error. The format is:</P>
<UL>
<LI>
<strong>ERR("SEV")—</strong>Severity of the error; where:
<br>
<br>
<ul>
<li>
<strong>Zero (0)—</strong>Warning.
<br>
<br>
</li>
<li>
<strong>1</strong>—Validation error.
<br>
<br>
</li>
<li>
<strong>2</strong>—Conformance error.
<br>
<br>
</li>
</ul>
</LI>
<LI>
<strong>ERR("MSG")—</strong>Brief text description of the error.
<BR>
<BR>
</LI>
<LI>
<strong>ERR("ARG")—</strong>Token value the triggered the error
(optional).
<BR>
<BR>
</LI>
<LI>
<strong>ERR("LIN")—</strong>Number of the line being processed
when the error occurred.
<BR>
<BR>
</LI>
<LI>
<strong>ERR("POS")—</strong>Character position within the line
where the error occurred.
<BR>
<BR>
</LI>
<LI>
<strong>ERR("XML")—</strong>Original document text of the line
where the error occurred.
</LI>
</UL>
</TD>
</TR>
</TABLE>
<H4><A NAME="example">Example</A></H4>
<P>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 <strong>BOOKS</strong>. Nested within that parent node are child nodes named <strong>TITLE</strong> and <strong>AUTHOR</strong>.</P>
<p>Remember the following:</p>
<ul>
<li>
The parent node is the node whose child nodes are being retrieved.
<br>
<br>
</li>
<li>
The child node, if specified, is the last child node retrieved. The function returns the next child in the list. If the parameter is
<strong>zero</strong> or missing, the first child is returned.
</li>
</ul>
<P>A sample client of the event-driven API is provided in the routine
MXMLTEST. This routine has an entry point <strong>EN(DOC,OPT)</strong>, where <strong>DOC</strong> and <strong>OPT</strong>
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.</P>
<ol>
<li>
Create an XML file:
<P><b>VistA XML Parser Use—Example: Create XML file</b></P>
<table width="100%"
border="1"
cellspacing="3"
cellpadding="3">
<tr>
<td>
<Pre>^TMP($J,1) = <?xml version=‘1.0’?>
^TMP($J,2) = <!DOCTYPE BOOK>
^TMP($J,3) = <BOOK>
^TMP($J,4) = <TITLE>Design Patterns</TITLE>
^TMP($J,5) = <AUTHOR>Author1</AUTHOR>
^TMP($J,6) = <AUTHOR>Author2</AUTHOR>
^TMP($J,7) = <AUTHOR>Author3</AUTHOR>
^TMP($J,8) = <AUTHOR>Author4</AUTHOR>
^TMP($J,9) = </BOOK></Pre>
</td>
</tr>
</table>
<br>
<br>
</li>
<li>
Invoke simple API for XML (SAX) interface:
<P><b>VistA XML Parser Use—Example: Simple API for XML (SAX) Interface</b></P>
<table width="100%"
border="1"
cellspacing="3"
cellpadding="3">
<tr>
<td>
<pre><b>D EN^MXMLTEST($NA(^TMP($J)),”V”)</b></pre>
</td>
</tr>
</table>
<br>
<br>
</li>
<li>
Check Document Object Model (DOM) interface:
<p><b>VistA XML Parser Use—Example: Check Document Object Model (DOM)
Interface</b></p>
<table width="100%"
border="1"
cellspacing="3"
cellpadding="3">
<tr>
<td>
<pre>><b>S HDL=$$EN^MXMLDOM($NA(^TMP($J)))</b>
><b>W $$NAME^MXMLDOM(HDL,1)</b>
BOOK
><b>S CHD=$$CHILD^MXMLDOM(HDL,1)</b>
><b>W $$NAME^MXMLDOM(HDL,CHD)</b>
TITLE
><b>W $$TEXT^MXMLDOM(HDL,CHD,$NA(VV))</b>
1
><b>ZW VV</b>
VV(1)=Design Patterns</pre>
</td>
</tr>
</table>
<br>
<br>
</li>
<li>
List all sibling nodes:
<p><b>VistA XML Parser Use—Example: List All Sibling Nodes</b></p>
<table width="100%"
border="1"
cellspacing="3"
cellpadding="3">
<tr>
<td>
<pre>><b>S CHD=$$CHILD^MXMLDOM(HDL,1)</b>
><b>S SIB=CHD</b>
><b>F S SIB=$$SIBLING^MXMLDOM(HDL,SIB) Q:SIB’>0 W !,SIB,?4,$$NAME^MXMLDOM(HDL,SIB)</b>
3 AUTHOR
4 AUTHOR
5 AUTHOR
6 AUTHOR
></pre>
</td>
</tr>
</table>
</li>
</ol>
<p> </p>
<!-- End Content -->
<footer>
<HR COLOR="003399">
<TABLE WIDTH="100%"
SUMMARY="This table for layout purposes only"
CLASS="white">
<TR>
<TD ALIGN="CENTER"
VALIGN="TOP">
<!--Start Bottom Links-->
<P ALIGN="CENTER">
<A HREF="http://www.va.gov/"
CLASS="bodylink"
TARGET="_top"
TITLE="Department of Veterans Affairs Internet Home Page">
<ACRONYM TITLE="Department of Veterans Affairs">VA</ACRONYM> (Internet)</A> /
<A HREF="http://vaww.va.gov/"
CLASS="bodylink"
TARGET="_top"
TITLE="Department of Veterans Affairs Intranet Home Page">
<ACRONYM TITLE="Department of Veterans Affairs">VA</ACRONYM>(Intranet)</A> /
<A HREF="http://vaww.va.gov/vhaoi/"
CLASS="bodylink"
TARGET="_top"
TITLE="Office of Information Home Page">
<ACRONYM TITLE="Veterans Health Adminstration Office of Health Information (OHI)">VHA OHI</ACRONYM></A> /
<A HREF="https://vaww.oit.va.gov/"
CLASS="bodylink"
TARGET="_top"
TITLE="Office of Information and Technology Home Page">
<ACRONYM TITLE="Office of Information and Technology (OIT)">OIT</ACRONYM></A> /
<A HREF="http://vista.med.va.gov/"
CLASS="bodylink"
TARGET="_top"
TITLE="Product Development (PD) Home Page">
<ACRONYM TITLE="Product Development">PD</ACRONYM></A> /
<A HREF="http://vista.med.va.gov/termsofuse.htm"
CLASS="bodylink"
TARGET="_top"
TITLE="Product Development (PD) Terms of Use Page">Terms of Use</A> /
<A HREF="http://www.va.gov/privacy/"
CLASS="bodylink"
TARGET="_top"
TITLE="Department of Veterans Affairs Privacy Policy">VA Privacy Policy</A> /
<A HREF="http://www1.va.gov/accessible/"
CLASS="bodylink"
TARGET="_top"
TITLE="Department of Veterans Affairs Internet Accessibility">Accessibility</A></P>
<!--End Bottom Links-->
<!--Date content was reviewed or updated-->
<P ALIGN="CENTER">Reviewed/Updated: 08/13/2018
<BR>
<BR>
For questions, comments, or accessibility issues with this website, please contact us by E-Mail:
<A HREF="mailto:[email protected]?subject=Web page comments from: /apis/en-mxmlprse.html"
TITLE="Send mail to the Webmasters regarding this page"
class="bodylink">Webmasters</A></P>
<P> </P>
</TD>
</TR>
</TABLE>
</footer>
</BODY>
</HTML>