NewDocument

NewDocument Syntax 1
NewDocument Syntax 2

Description

The NewDocument method is overloaded:

Syntax 1 creates a new XML DOM document using the name of the root element to be contained within the new DOM document.
Syntax 2 creates a new XML DOM document using the name and namespace URI of the root element to be contained in the new DOM document, and also the external subset public and system identifiers.

Syntax

For this syntax	See
NewDocument(string strRootElementName)	NewDocument Syntax 1
NewDocument( string strRootElementNamespacePrefix, stringstrRootElementNamespaceURI, string strRootElementName, string strDocTypePublicId, string strDocTypeSystemId)	NewDocument Syntax 2

For this syntax

See

NewDocument(string strRootElementName)

NewDocument Syntax 1

NewDocument(
string strRootElementNamespacePrefix, stringstrRootElementNamespaceURI, 
string strRootElementName, 
string strDocTypePublicId, 
string strDocTypeSystemId)

NewDocument Syntax 2

NewDocument Syntax 1

Description

Creates a new XML DOM document from scratch.

Syntax

pbdom_document_name.NewDocument(strRootElementName)

Argument	Description
pbdom_document_name	The name of a PBDOM_DOCUMENT object
strRootElementName	The name of the root element to be contained in the DOM document

Return value

Boolean.

Returns true if a new document is successfully created and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT -- The input string is invalid, which can occur if the string was set to null by means of the PowerScript SetNull method.

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.

Usage

The parameter strRootElementName becomes the name of the root element.

See also

SaveDocument

NewDocument Syntax 2

Description

Creates a new XML DOM document from scratch.

Syntax

pbdom_document_name.NewDocument(string strRootElementNamespacePrefix, string strRootElementNamespaceURI, string strRootElementName, string strDocTypePublicId, string strDocTypeSystemId)

Argument	Description
pbdom_document_name	The name of a PBDOM_DOCUMENT object.
strRootElementNamespacePrefix	The namespace prefix of the root element to be contained in the DOM document. This can be an empty string.
strRootElementNamespaceURI	The namespace URI of the root element to be contained in the DOM document. This can be an empty string.
strRootElementName	The name of the root element to be contained in the DOM document.
strDocTypePublicId	The external subset public identifier.
strDocTypeSystemId	The external subset system identifier.

Return value

Boolean.

Returns true if a new document is successfully created, and false otherwise.

Throws

EXCEPTION_INVALID_ARGUMENT -- One of the input strings is invalid. This can happen if the string has been set to null using the PowerScript SetNull method.

EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.

EXCEPTION_INVALID_NAME -- The root element name, or the root element namespace prefix or URI, is invalid.

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_DOCUMENT object's internal implementation is NULL. The occurrence of this exception is rare but can take place if severe memory corruption occurs.

Examples

This example attempts to create a PBDOM_DOCUMENT object in which the root element belongs to no namespace, as indicated by the empty strings for the namespace prefix and URI arguments to NewDocument:
```
PBDOM_DOCUMENT pbdom_doc

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_doc.NewDocument ("", "", "root", "public_id", &
     "system_id.dtd")

  pbdom_doc.SaveDocument &
     ("new_document_no_namespace.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
```
When serialized, the XML document looks like the following:
```
<!DOCTYPE root PUBLIC "public_id" "system_id.dtd">
<root xmlns=""/>
```
The namespace declaration attribute (xmlns="") present in the root element indicates that the root element belongs to no namespace.
This example attempts to create a PBDOM_DOCUMENT object in which the root element belongs to a default namespace. The URI is http://www.pre.com, which means that the root element belongs to the namespace http://www.pre.com. The prefix is an empty string, which means that the root element belongs to the http://www.pre.com namespace by default:
```
PBDOM_DOCUMENT pbdom_doc

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_doc.NewDocument ("", "http://www.pre.com", &
     "root", "public_id", "system_id.dtd")

  pbdom_doc.SaveDocument &
     ("new_document_default_namespace.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
```
When serialized, the XML document looks like the following:
```
<!DOCTYPE root PUBLIC "public_id" "system_id.dtd">
<root xmlns="http://www.pre.com"/>
```
The namespace declaration attribute (xmlns="http://www.pre.com") present in the root element indicates that the root element belongs to the default namespace http://www.pre.com. All child elements of root belong to this same namespace unless another in-scope namespace declaration is present and is used.
This example attempts to create a PBDOM_DOCUMENT object in which the root element belong to a prefixed namespace. The namespace prefix is pre and the URI is http://www.pre.com. This means that the root element will belong to the namespace http://www.pre.com, and that the root element will have a namespace prefix of pre:
```
PBDOM_DOCUMENT pbdom_doc

try
  pbdom_doc = Create PBDOM_DOCUMENT
  pbdom_doc.NewDocument ("pre", "http://www.pre.com", &
     "root", "public_id", "system_id.dtd")

  pbdom_doc.SaveDocument &
     ("new_document_namespace.xml")

catch (PBDOM_EXCEPTION except)
  MessageBox ("PBDOM_EXCEPTION", except.GetMessage())
end try
```
When serialized, the XML document looks like the following:
```
<!DOCTYPE pre:root PUBLIC "public_id" "system_id.dtd">
<pre:root xmlns:pre="http://www.pre.com"/>
```
A namespace declaration attribute (xmlns:pre="http://www.pre.com") is present in the root element. The root element also contains a pre prefix. This indicates that the root element belongs to the namespace http://www.pre.com.

However, the fact that the http://www.pre.com namespace is prefixed by pre indicates that the child elements of root belong to this same namespace only if their qualified names also contain the pre prefix and there is an in-scope namespace declaration for http://www.pre.com that is prefixed by pre.

Usage

Using the five parameters available with this syntax provides more control over the DOCTYPE definition of the document.

See also

SaveDocument

Prev	Up	Next
IsAncestorObjectOf	Home	RemoveContent

PowerBuilder Extension ReferencePBDOM_DOCUMENT

NewDocument

NewDocument Syntax 1

NewDocument Syntax 2

PowerBuilder Extension Reference
PBDOM_DOCUMENT