User Guide : Scripting : Script Objects : DOMDocument Object Type
 
Share this page                  
DOMDocument Object Type
The DOMDocument type represents an XML document. It contains at least one node, of type DOM_ELEMENT_NODE, which is the root element of the document.
The following are four ways to create a DOMDocument:
Use the ParseXML Function on a string. The string is expected to be a byte representation of the XML document (i.e. each Unicode character in the string contains character values from 0 to 255).
Dim doc As DOMDocument
Dim xml
xml = "<abc><def>text</def></abc>"
Set doc = ParseXML(xml)
Use the ParseXMLFile Function on a file. The file may represent a URI.
Dim doc As DOMDocument
Set doc = ParseXMLFile("testfile.xml")
Use the New Operator. This requires one parameter, which is the name of the root element of the document.
Dim doc As DOMDocument
Set doc = New DOMDocument "DOMTest"
Use the Self Property to pass a reference to the DOMDocument object for a user-defined function. For an example of how to refer to an object inside a user-defined function, see DocumentElement Property.
Dim doc As DOMDocument
userFunction(doc.self)
The DOMDocument supports a few properties and methods, mostly concerned with getting or creating DOMNode objects.
Properties
 
Property
Type
Access
Description
DocumentElement Property
DOMNode
RO
Get the root element of the document.
Self Property
DOMDocument
RO
Return a reference to the DOMDocument object.
DocumentElement Property
The DocumentElement property returns the root element of the DOMDocument.
Syntax
dom.DocumentElement
Parameters
 
Type
Required
Description
DOMDocument
Yes
Reference to the DOMDocument that is the subject of the property or method invocation.
Example
'The following example shows how to get the root element from a DOMDocument called doc.
Dim rootnode As DOMNode
Set rootnode = doc.DocumentElement
Self Property
The Self property is used for getting a reference to an object that can then be passed as an argument to a function or method call. The reason for having a special property for getting the object reference is to resolve an ambiguity with the default property, Value. This is similar to the distinction between normal variable assignment (Let) the use of Set for assigning object variables. When a DOMDocument object variable is used without an associated property or method, the integration language processor assumes an implied access of the Value property.
Syntax
doc.Self
Parameters
 
Type
Required
Description
DOMDocument
Yes
Reference to the DOMDocument object which is the subject of the property or method invocation.
Example
'This example shows how to refer to an object inside a user-defined function.
Function userFunction(doc As DOMDocument)
  Dim rootNode As DOMNode
  Set rootNode = doc.DocumentElement
'...
End Function
Methods
 
Method
Type
Description
CreateCDATASection Method
DOMNode
Create a CDATA node.
CreateElement Method
DOMNode
Create a DOM element node.
CreateTextNode Method
DOMNode
Create a text node.
Print Method
String
Print the DOM object to an XML string.
CreateElement Method
This method creates a new document element with a DJNode type of DOM_ELEMENT_NODE and with the name. A reference to the new DJNode object is returned as the result of the method.
Syntax
dom.CreateElement(name)
Parameters
 
Type
Required
Description
DOMDocument
Yes
Reference to the DOMDocument object that is the subject of the property or method invocation.
String
Yes
Name for the new element node.
Exceptions
The CreateElement method may return the following exceptions if there is an error at run time.
Exception
Description
ERR_DOMERROR
Returned if the method is unable to create the new element.
Example
'The follow code snippet creates a new element, TestNode, in the DomDocument doc.
Dim newnode As DOMNode
Set newnode = doc.CreateElement("TestNode")
CreateTextNode Method
This method creates a new document element with a DJNode type of DOM_TEXT_NODE. A reference to the new DJNode object is returned as the result of the method.
Syntax
dom.CreateTextNode(pcdata)
Parameters
 
Type
Required
Description
DOMDocument
Yes
Reference to the DOMDocument object that is the subject of the property or method invocation.
String
Yes
String expression used to provide the initial data for the object.
Exceptions
The CreateTextNode method may return the following exceptions if there is an error at run time.
Exception
Description
ERR_DOMERROR
Returned if the method is unable to create the new element.
Example
'Creates a new DOMNode for holding parsed character data.
Dim newnode As DOMNode
Set newnode = doc.CreateTextNode("Some PCDATA")
CreateCDATASection Method
This method creates a new document element with a DJNode type of DOM_CDATA_SECTION_NODE. A reference to the new DJNode object is returned as the result of the method.
Syntax
dom.CreateCDATASection(cdata)
Parameters
 
Type
Required
Description
DOMDocument
Yes
Reference to the DOMDocument object that is the subject of the property or method invocation.
String
Yes
String expression used to provide the initial data for the object.
Exceptions
The CreateCDATASection method may return the following exceptions if there is an error at run time.
Exception
Description
ERR_DOMERROR
Returned if the method is unable to create the new element.
Example
'The follow code snippet creates a new DOMNode for holding character data.
Dim newnode As DOMNode
Set newnode = doc.CreateCDATASection("Some character data")
Print Method
Use the Print method to print a DOMDocument object to a string. The Print method accepts three optional parameters. The first is the encoding to use (one of the ENC_xxx constants). If not supplied, the default is UTF-8. The second parameter is a Boolean indicating whether to print an XMLDecl line; the default value is TRUE. The third parameter is a Boolean indicating whether to attempt to "pretty-print" the document. If set to TRUE, an attempt is made to insert indentation and newlines to make the result easier to read. The default is FALSE.
Syntax
documentName.Print([encoding][, xmldecl][, prettyprint])
Parameters
 
Name
Type
Required
Description
documentName
DOMDocument
Yes
Reference to the DOMDocument object that is the subject of the property or method invocation.
encoding
Integer
No
Character set to use for encoding the printed document.
xmldecl
Boolean
No
Flag indicating whether or not to include an XMLDecl line.
prettyprint
Boolean
No
Flag indicating whether or not to use pretty-printing.
Exceptions
The Print method may return the following exceptions if there is an error at run time.
Exception
Description
ERR_DOMERROR
Returned if the method is unable to print the document.
Example
'The follow code snippet prints a DOMDocument doc using UTF-8 encoding. The printed document will include an XMLDecl statement and the document is printed without pretty-printing.
Dim pxml
pxml = doc.Print(ENC_UTF8, TRUE, FALSE)
Operators
 
Operator
Type
Description
New
DOMDocument
Create a new object.
New Operator
The New operator creates a new instance of a DOMDocument object. The operator returns a reference to the new object. Typically, this reference is assigned to an object variable that has been declared with a compatible type. The assignment is done using the Set statement.
Syntax
New DOMDocument
Example
Dim doc As DOMDocument
Set doc = New DOMDocument "DOMTest"