add Method

MSXML 5.0 SDK

Microsoft XML Core Services (MSXML) 5.0 for Microsoft Office - DOM Reference

add Method

Adds a new schema to the schema collection and associates the given namespace URI with the specified schema.

[Script]

Script Syntax

objXMLDOMSchemaCol.add(namespaceURI, var);

Parameters

namespaceURI
The namespace to associate with the specified schema. The empty string, "", will associate the schema with the empty namespace, xmlns="".

This may be any string that can be used in an xmlns attribute, but it cannot contain entity references. The same white space normalization that occurs on the xmlns attribute also occurs on namespaceURI (that is, leading and trailing white space is trimmed, new lines are converted to spaces, and multiple adjacent white space characters are collapsed into one space).

var
This specifies the schema to load. It will load it synchronously and with resolveExternals=false and validateOnParse=false. This parameter can also take any DOMDocument as an argument.

This argument can be Null, which results in the removal of any schema for the specified namespaces. If the schema is an IXMLDOMNode, the entire document the node belongs to will be preserved.

Example

The following script example attaches a schema to an XML document.

var xmldoc = new ActiveXObject("Msxml2.FreeThreadedDOMDocument.5.0");
var SchemaCache = new ActiveXObject("Msxml2.XMLSchemaCache.5.0");

xmldoc.async = false;
xmldoc.validateOnParse = false;
SchemaCache.add("x-schema:books", "c:\\books.xsd");
xmldoc.schemas = SchemaCache;
// The document will load only if a valid schema is attached to the xml
// file.
xmldoc.load("c:\\books.xml");
if (xmlDoc.parseError.errorCode <> 0) {
   var myErr = xmlDoc.parseError;
   alert("You have error " + myErr.reason);
} else {
   alert(xmldoc.xml) ;
}
[Visual Basic]

Visual Basic Syntax

objXMLDOMSchemaCol.add(namespaceURI, var)

Parameters

namespaceURI
This is the namespace to associate with the specified schema. The empty string, "", will associate the schema with the empty namespace, xmlns="".

This may be any string that can be used in an xmlns attribute, but it cannot contain entity references. The same white space normalization that occurs on the xmlns attribute also occurs on namespaceURI (that is, leading and trailing white space is trimmed, new lines are converted to spaces, and multiple adjacent white space characters are collapsed into one space).

var
Specifies the schema to load. It will load it synchronously and with resolveExternals=false and validateOnParse=false. The schema parameter can also be any DOMDocument.

This argument can be Null, which results in the removal of any schema for the specified namespaces. If the schema is an IXMLDOMNode, the entire document the node belongs to will be preserved.

Example

The following Visual Basic example attaches a schema to an XML document.

Dim xmldoc As New Msxml2.FreeThreadedDOMDocument50
Dim SchemaCache As New Msxml2.XMLSchemaCache50

xmldoc.async = False
xmldoc.validateOnParse = True
SchemaCache.Add "x-schema:books", "c:\books.xsd"
Set xmldoc.schemas = SchemaCache
' The document will load only if a valid schema is attached to the xml
' file.
xmldoc.Load "c:\books.xml"
If (xmlDoc.parseError.errorCode <> 0) Then
   Dim myErr
   Set myErr = xmlDoc.parseError
   MsgBox("You have error " & myErr.reason)
Else
   MsgBox xmldoc.xml
End If
[C/C++]

C/C++ Syntax

HRESULT add(BSTR namespaceURI, VARIANT var);

Parameters

namespaceURI [in]
The namespace to associate with the specified schema.

The empty string, "", will associate the schema with the empty namespace, xmlns="". This may be any string that can be used in an xmlns attribute, but it cannot contain entity references. The same white space normalization that occurs on the xmlns attribute also occurs on this parameter (that is, leading and trailing white space is trimmed, new lines are converted to spaces, and multiple adjacent white space characters are collapsed into one space).

var [in]
This specifies the schema. It can be a BSTR, in which case it points to the URL to load. It will load it synchronously and with resolveExternals=false and validateOnParse=false. The var parameter can also be any DOMDocument.

This argument can be Null, which results in the removal of any schema for the specified namespaces. If the schema is an IXMLDOMNode, the entire document the node belongs to will be preserved.

C/C++ Return Values

If this call fails, the collection remains unchanged. E_FAIL is returned if:

  • The collection is read-only.
  • The document is not a recognized schema.
  • An error occurs when compiling the schema.
  • The ready state of the document is not 4.

If it was loading a schema and encountered a parse error, then the parse error reason is returned in the IErrorInfo. If the VARIANT argument contains an invalid value, E_INVALIDARG is returned.

Example

#include "stdafx.h"
#include "tchar.h"
#import "c:\\winnt\\system32\\msxml5.dll"
using namespace MSXML2;

void AddCollectionSample();

int APIENTRY WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPSTR     lpCmdLine,
                     int       nCmdShow)
{
   ::CoInitialize(NULL);
   AddCollectionSample();
   ::CoUninitialize();
   return 0;
}

void AddCollectionSample()
{
   IXMLDOMDocument2Ptr pIXMLDOMDocument2;
   IXMLDOMSchemaCollection2Ptr pIXMLDOMSchemaCollection2Ptr;
   int nResult;
   
   try
   {
   // Create the DOM
      nResult = pIXMLDOMDocument2.CreateInstance(__uuidof(MSXML2::DOMDocument50));
      (nResult == 0) ? 0: throw nResult;

   // Create the Schema Collections
      nResult = pIXMLDOMSchemaCollection2Ptr.CreateInstance(__uuidof(MSXML2::XMLSchemaCache50));
      (nResult == 0) ? 0: throw nResult;
   
   // Add the schema to the collection
      nResult = pIXMLDOMSchemaCollection2Ptr->add(_T("x-schema:books"), _T("c:\\books.xsd"));
      (nResult == 0) ? 0: throw nResult;
      
   // Attach schemas
      pIXMLDOMDocument2->schemas = pIXMLDOMSchemaCollection2Ptr.GetInterfacePtr();

      pIXMLDOMDocument2->async = false;
      pIXMLDOMDocument2->validateOnParse = true;

   // Load the document into the DOM
      nResult = pIXMLDOMDocument2->load(_T("c:\\books.xml"));
      (nResult == -1) ? 0: throw nResult;

      ::MessageBox(NULL, pIXMLDOMDocument2->xml, _T("Loaded Document"), MB_OK);
   } catch(...)
   {
      ::MessageBox(NULL, _T("Sample Failed"), _T("Error"), MB_OK);
   }
}

File Name: c:\books.xml

<?xml version='1.0'?>
<Collection xmlns="x-schema:books">
   <Book>
      <Title>Lover Birds</Title>
      <Author>Cynthia Randall</Author>
      <Publisher>Lucerne Publishing</Publisher>
   </Book>
</Collection>

File Name: c:\books.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
   <xs:element name="Collection">
      <xs:complexType>
    <xs:sequence>
       <xs:element name="OtherBook">
          <xs:complexType>
        <xs:sequence>
         <xs:element name="Title" type="xs:string"/>
         <xs:element name="Author" type="xs:string"/>
         <xs:element name="Publisher" type="xs:string"/>
        </xs:sequence>
          </xs:complexType>
       </xs:element>
    </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Output (in a message box)

<?xml version='1.0'?>
<Collection xmlns="x-schema:books">
   <Book>
      <Title>Lover Birds</Title>
      <Author>Cynthia Randall</Author>
      <Publisher>Lucerne Publishing</Publisher>
   </Book>
</Collection>

Remarks

Schemas referenced by this schema are not added to the collection. The contents of the schema are added to the internal collection. (The schema can be copied.) If a schema is already in the collection with this namespace, the new one will replace it.

The XmlSchemaCache object does not retrieve imported or included schemas during validation if validateOnLoad is set to False. In this situation, if a.xsd imports or includes another schema file, b.xsd, and you need to use the add method to add b.xsd separately to the schema cache as shown in the following sample JScript code for validation to run successfully as expected:

var schemas = new ActiveXObject("MSXML2.XMLSchemaCache.5.0");
schemas.validateOnLoad = false
schemas.add("http://www.example.com/a/", "a.xsd");
/* Add all imported/included schemas by hand */
schemas.add("http://www.example.com/b/", "b.xsd"); 
schemas.validate()

This only applies if you are not using the default setting of True for validateOnLoad. For example, the following code below will import and inlcude b.xsd if it is referenced in a.xsd.

var schemas = new ActiveXObject("MSXML2.XMLSchemaCache.5.0");
schemas.validateOnLoad = true; /* THIS IS THE DEFAULT */ 
schemas.add("http://www.example.com/a/", "a.xsd");
schemas.validate()

To view reference information for Visual Basic, C/C++, or Script only, click the Language Filter button Language Filter in the upper-left corner of the page.

See Also

Applies to: IXMLDOMSchemaCollection/XMLSchemaCache