XmlNewDoc Function

Creates a new XML document in memory as an XML Document Object Model (DOM). By default the version of XML is set to 1.0.

Usage

document_id = XmlNewDoc(root_name)

Input Parameters

root_name—A String containing the name of the top element in the tree.

Returned Value

document_id—A new document handle.

Keywords

DTD—A string containing the URL to a DTD file, or the path to a local DTD file if the /Internal flag is used.

Href—A string containing the global href for the namespace.

Internal—If present, DTD will be inserted in the XML document.

Prefix—A string containing the global prefix for the namespace.

PubInd—Public Identifier.

Version—A string containing the XML version number to use in the XML prolog. By default the value “1.0” is used.

Discussion

You can use XmlNewDoc in conjunction with the routines XmlNewNode, XmlAddNode, and XmlSetAttr to create an XML DOM entirely from scratch in memory. The XmlDocDump would then typically be used to output this XML document to a string or a file.

Here are more details on the parameters for XmlNewDoc which all add information to the prolog (header) of the XML document:

Root_Name—This XML prolog declaration allows you to specify a document type name. A Document Type Definition (DTD) is often used in conjunction with this declaration to specify the details of how a document with this type name is structured.

Public Identifier—This optional entry in the XML prolog allows the ability to look up a DTD in catalogs on the client side without having to locate it on the web. A local catalog must be provided so that other tools can map this identifier to a local DTD file. Please consult a good XML reference for more details on public identifiers.

DTD—This optional entry in the XML prolog specifies the DTD or Document Type Definition which should be used when the document is parsed to verify that the XML document conforms to a predefined set of rules. A local file path or a web URL can be used to specify the path to the DTD. Using the /Internal flag will copy the contents of the DTD to the XML document so that an external reference is not required.

Prefix and Href—These optional XML prolog parameters allow you to identify a namespace for your XML document. A namespace in an XML file allows you to separate your element or node names from other XML element or node names in other files that might have the same base name. It makes your XML document unique. It is useful when parsing a well-formed XML document without a DTD.

Example 1

This example creates a new XML document with “Chart” as its root element and has a default version of “1.0”.

; Initialize a DOM tree.

new_doc = XmlNewDoc('Chart')

Example 2

This example creates a new XML document with an external DTD.

; Create a DOM tree with a DTD.

new_doc = XmlNewDoc('Chart', DTD='xml-1_0/data/chart.dtd')

Example 3

This example creates a new XML document with an internal DTD.

; DOM tree with an internal DTD copied from an external file.

new_doc = XmlNewDoc('Chart', DTD='xml-1_0/data/chart.dtd', $

   /Internal)

Example 4

This example creates a new XML document with namespaces.

new_doc = XmlNewDoc('Chart', Prefix='pvwave', $

   Href='http://www.perforce.com')