M XML PARSER ICR (3561)

Name

Value

NUMBER

3561

IA #

3561

DATE CREATED

2003/07/03

CUSTODIAL PACKAGE

TOOLKIT

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

MXMLDOM

NAME

M XML PARSER

GENERAL DESCRIPTION

This utility provides a M based XML version 1.0 parser.

It supports both the SAX interface and the DOM interface.

STATUS

Active

MXMLDOM

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

$$EN

This is the entry point to perform initial processing
of the XML document.  The client application must first call this entry point
to build the in-memory image of the document before the remaining methods can
be applied.  The return value is a handle to the document instance that was
created and is used by the remaining API calls to identify a specific document
instance.

VARIABLES

TYPE

VARIABLES DESCRIPTION

DOC

Input

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 must either be stored
in standard 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   ...

OPT

Input

A list of option flags that control parser behavior.
Recognized option flags are:

0 = Terminate parsing on encountering a warning. (By default, the parser
terminates only when a conformance or validation error is encountered.)

$$EN

Output

Returns a nonzero handle to the document instance if
parsing completed successfully, or zero otherwise.  This handle is passed to
all other API methods to indicate which document instance is being referenced.
This allows for multiple document instances to be processed concurrently.

DELETE

Deletes the specified document instance.  A client
application should always call this entry point when finished with a document
instance.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.

$$NAME

Returns the name of the element at the specified node
within the document parse tree.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HANDLE

Input

The value returned by the $$EN^MXMLDOM call that
created the in-memory document image.

NODE

Input

The node whose associated element name is being
retrieved.

$$NAME

Output

The name of the element associated with the specified
node.

$$CHILD

Returns the node of the first or next child of a
given parent node, or 0 if there are none remaining.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.
PARENT	Input	The node whose children are being retrieved.
CHILD	Input	If specified, this is the last child node retrieved. The function will return the next child in the list. If the parameter is zero or missing, the first child is returned.
$$CHILD	Output	The next child node or zero if there are none remaining.

$$SIBLING

Returns the node of the specified node's immediate
sibling, or 0 if there is none.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HANDLE

Input

The value returned by the $$EN^MXMLDOM call that
created the in-memory document image.

NODE

Input

The node in the document tree whose sibling is being
retrieved.

$$SIBLING

Output

The node corresponding to the immediate sibling of
the specified node, or zero if there is none.

$$PARENT

Returns the parent node of the specified node, or 0
if there is none.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HANDLE

Input

The value returned by the $$EN^MXMLDOM call that
created the in-memory document image.

NODE

Input

The node in the document tree whose parent is being
retrieved.

$$PARENT

Output

The parent node of the specified node, or zero if
there is no parent.

TEXT

Extracts non-markup text associated with the
specified node.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HANDLE

Input

The value returned by the $$EN^MXMLDOM call that
created the in-memory document image.

NODE

Input

The node in the document tree that is being
referenced by this call.

TEXT

Both

This parameter must contain a closed local or global
array reference that is to receive the text.  The specified array is deleted
before being populated.

$$TEXT

Extracts non-markup text associated with the
specified node.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.
NODE	Input	The node in the document tree that is being referenced by this call.
TEXT	Both	This parameter must contain a closed local or global array reference that is to receive the text. The specified array is deleted before being populated.
$$TEXT	Output	If called as an extrinsic function, the return value is true if text was retrieved, or false if not.

CMNT

Extracts comment text associated with the specified
node.

VARIABLES

TYPE

VARIABLES DESCRIPTION

HANDLE

Input

The value returned by the $$EN^MXMLDOM call that
created the in-memory document image.

NODE

Input

The node in the document tree that is being
referenced by this call.

TEXT

Both

This parameter must contain a closed local or global
array reference that is to receive the text.  The specified array is deleted
before being populated.

$$CMNT

Extracts comment text associated with the specified
node.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.
NODE	Input	The node in the document tree that is being referenced by this call.
TEXT	Both	This parameter must contain a closed local or global array reference that is to receive the text. The specified array is deleted before being populated.
$$CMNT	Output	If called as an extrinsic function, the return value is true if text was retrieved, or false if not.

$$ATTRIB

Retrieves the first or next attribute associated with
the specified node.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.
NODE	Input	The node whose attribute name is being retrieved.
ATTRIB	Output	The name of the last attribute retrieved by this call. If null or missing, the first attribute associated with the specified node is returned. Otherwise, the next attribute in the list is returned.
$$ATTRIB	Output	The name of the first or next attribute associated with the specified node, or null if there are none remaining.

$$VALUE

Retrieves the value associated with the named
attribute.

VARIABLES	TYPE	VARIABLES DESCRIPTION
HANDLE	Input	The value returned by the $$EN^MXMLDOM call that created the in-memory document image.
NODE	Input	The node whose attribute value is being retrieved.
ATTRIB	Input	The name of the attribute whose value is being retrieved by this call.
$$VALUE	Output	The value associated with the specified attribute.