Loads an XML file dynamically by the specified URI, parses it and adds the new XML document to the list of all open documents provided by #DOCUMENTS element.

The repeating requests to load the same XML file (i.e. the one located by the same URI) are resolved according to the following.

When the parameter key is absent, on each subsequent request to load the same XML file, the function does nothing and just returns some already loaded XML document instance of that file.

When the parameter key is specified, it must provide an additional hash-key that will be associated with the loaded XML document instance returned by the function. Now, only the entire pair {URI; key} must be unique. If the specified XML file has never been read, a new XML document instance will be loaded from it, associated with the key and returned by the function. Otherwise, there may be two situations:

  1. There is some XML document instance already loaded from that file, but it is not yet associated with any key (the case when it is a leftover from an early loadXMLDocument(xmlURI) call). Then, that instance will be used -- associated with the key and returned by the function.
  2. All XML document instances already loaded from the specified XML file are associated with other keys. In that case, the file will be loaded once again into a new XML document instance, which will be associated with the specified key and returned by the function.
Such functionality may be necessary when several different XML documents must be produced from the same original XML file by slightly changing each loaded XML document instance dynamically in memory (e.g. by adding to it some service attributes; see setServiceAttr() function).

Note: Any error that happens during the opening, reading and parsing of the XML file will be reported by the function.

Parameter:

xmlURI

The URI of the XML file to load. This may be a URL or an absolute pathname on the local system.

Note: When the specified URI is an empty (or blank) string, the function returns null.

key
The additional key to control the repeated loading of the same XML file.

Returns:

The DSM element of #DOCUMENT type that represents the new (or already open) XML document.

See Also:

All Element Types | #DOCUMENT, #DOCUMENTS;
findXMLDocument(), getXMLDocument()