The IDLffXMLDOMDocument::Init function method initializes the object. It can also load and parse an XML document, using the same keywords that IDLffXMLDOMDocument::Load does. (For more information on loading, see that method’s description.)

Syntax

Obj = OBJ_NEW(‘IDLffXMLDOMDocument’ [, /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])

or

Result = Obj->[IDLffXMLDOMDocument::]Init( [, /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] )     (In a lifecycle method only.)

Return Value

Returns an object reference to the newly created object when this method is called indirectly, as part of the call to the OBJ_NEW function.

Returns 1 if initialization was successful or 0 otherwise, when this method is called directly within a subclass Init method.

Arguments

None

Keywords

Note: Any property listed under IDLffXMLDOMDocument Properties that contains the word “Yes” in the “Init” column of the property table can be initialized during object creation using this method. To initialize the value of a property, specify the property name as a keyword set equal to the appropriate property value.

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 to a scalar string containing the name of the XML file to load and parse.

The FILENAME keyword 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