The IDLffXMLDOMDocument::Load procedure method loads XML data from the source specified by the FILENAME keyword. The XML parser then parses the data, using any related DTD or schema specifications. The results of the parse are used to construct a DOM document tree that can then be accessed through this document object.

If the FILENAME keyword is not specified, the other keywords have no effect and the DOM document tree is unchanged. If it is specified, then any existing DOM document tree is destroyed, and the results of the parsing operation are used to create a new DOM document tree.

Note: This method invalidates all object references to node objects created with the previous document.

IDL issues messages for any parser warnings or errors unless the QUIET keyword is set. If a parsing error that is more severe than a warning is encountered during parsing, IDL issues a single additional message after parsing and returns to the interpreter, even if QUIET is set. The IDL CATCH facility can intercept this message. If this message is issued, the document tree is empty, containing no nodes.

Syntax

Obj->[IDLffXMLDOMDocument::]Load [, /EXCLUDE_IGNORABLE_WHITESPACE] [, /EXPAND_ENTITY_REFERENCES] [, FILENAME=string | STRING=string] [, MSG_ERROR=string] [, MSG_FATAL=string] [, MSG_WARNING=string] [, /QUIET] [, SCHEMA_CHECKING=value] [, VALIDATION_MODE=value]

Arguments

None

Keywords

EXCLUDE_IGNORABLE_WHITESPACE

Set this keyword to prevent text nodes containing ignorable white space from being inserted into the DOM tree. The default action is to include these nodes in the DOM tree. Note that in order for the parser to distinguish between ignorable and non-ignorable white space, validation must be turned on with the VALIDATION_MODE keyword and there must be a DTD. This keyword has no effect if VALIDATION_MODE is 0 or if there is no DTD for the XML document.

EXPAND_ENTITY_REFERENCES

Set this keyword to cause the parser to replace entity references with their fully expanded substitution text. If entity references are not expanded, the DOM parser creates entity-reference nodes in the DOM tree. The children of the entity-reference nodes are read-only and are elements containing the entity values. If entity references are expanded, the DOM parser creates no entity-reference nodes in the DOM tree and instead creates read-write nodes that correspond to the fully expanded substitution text.

FILENAME

Set this keyword equal to a scalar string containing the name of the XML file to load and parse. If this keyword is not specified, the other keywords have no effect and the DOM document tree is unchanged. If it is specified, then any existing DOM document tree is destroyed, and the results of the parsing operation are used to create a new DOM document tree.

The keyword string can also specify a URL. In this case, the object reads the XML data from the specified URL over the network and builds the document tree without the XML data needing to be present in a local file.

Setting both the FILENAME and STRING keywords causes an error.

The following example reads XML from an RSS feed containing weather information for Denver, Colorado:

FUNCTION filter, oNode
   name = oNode->getNodeName()
   IF name EQ 'title' OR name EQ 'description' THEN $
      RETURN, 1 ; accept
   RETURN, 3 ;; skip
END
 
PRO weather
   oDoc = OBJ_NEW( 'IDLffXMLDOMDocument', $
      FILENAME='http://weather.gov/data/current_obs/KDEN.rss' )
   oNodeIterator = oDoc->createNodeIterator( OBJ_NEW(), $
      FILTER_NAME='filter' )
 
   oNode = oNodeIterator->nextNode()
   WHILE OBJ_VALID( oNode ) DO BEGIN
      ; Assuming only one text node per element
      PRINT, (oNode->GetFirstChild())->getNodeValue()
      oNode = oNodeIterator->nextNode()
   ENDWHILE
   PRINT
   OBJ_DESTROY, oDoc
END

MSG_ERROR

Set this keyword to a scalar string that contains the name of an IDL procedure that will be called when the parser generates an error message. The following procedure parameters are required:

  • Filename – A scalar string containing the name of the file being parsed
  • Line number – A scalar integer containing the line number in the file where the parsing error occurred
  • Column number – A scalar integer containing the column number in the file where the parsing error occurred
  • Message – A scalar string containing the parser error message

MSG_FATAL

Set this keyword to a scalar string that contains the name of an IDL procedure that will be called when the parser generates a fatal error message. The required procedure parameters are the same as for MSG_ERROR.

MSG_WARNING

Set this keyword to a scalar string that contains the name of an IDL procedure that will be called when the parser generates a warning message. The required procedure parameters are the same as for MSG_ERROR.

QUIET

Set this keyword to prevent IDL from printing out informational parser warnings and error messages. The default action is to report all parser warnings and errors with messages. If an error more severe than a warning is encountered, IDL issues an additional single message after parsing is complete and returns to the interpreter, regardless of this keyword’s setting.

SCHEMA_CHECKING

Set this keyword to an integer value to indicate the type of validation the parser should perform. XML schemas describe the structure and allowed contents of an XML document. Schemas are more robust than, and are envisioned as a replacement for, DTDs. By default, the parser will validate the parsed XML file against the specified schema, if one is provided. If no schema is provided, no validation occurs.

Possible values are:

0

No schema checking is performed.

1

Schema checking is performed only if a schema is provided. This is the default value.

2

Full schema constraint checking is performed if a schema is provided. This feature checks the schema grammar itself for additional errors.

STRING

Set this keyword equal to a scalar string containing the XML Document text. Setting the STRING keyword avoids the need for file input/output operations. As a result, setting both the FILENAME and STRING keywords causes an error.

If the XML Document text contains references to local files, IDL’s current working directory should be set to the directory containing those files. To avoid the need to manage the current working directory, use this keyword with self-contained XML documents. For example, placing DTD information in a DOCTYPE element in the document text avoids the need for an external file reference.

VALIDATION_MODE

Set this keyword to one of the following values:

0

The parser does not report validation errors.

1

The parser reports validation errors only if a DTD is specified. This is the default value.

2

The parser always reports validation errors.

This keyword ignores all other values.

Version History

6.1

Introduced

6.2

Added SCHEMA_CHECKING keyword

6.4

Added STRING keyword