add Method (IXMLDOMSchemaCollection/XMLSchemaCache)

 

Description

 

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

 

PowerBASIC Syntax

 

METHOD add ( _

BYVAL NamespaceURI AS STRING, _

BYVAL vVar AS VARIANT _

)

 

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 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).

vVar

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.

 

OBJRESULT

 

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.

 

Remarks for MSXML 4.0 and MSXML 5.0

 

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, you need to use the add method to add b.xsd separately to the schema cache for validation to run successfully as expected. The following JScript code is an example.

 

var schemas = new ActiveXObject("MSXML2.XMLSchemaCache.4.0");

 

schemas.add("http://www.example.com/a/", "a.xsd");

/* Add all imported/included schemas by hand */

 

schemas.validate()

 

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

 

var schemas = new ActiveXObject("MSXML2.XMLSchemaCache.4.0");

schemas.validateOnLoad = true; /* THIS IS THE DEFAULT */

schemas.add("http://www.example.com/a/", "a.xsd");

schemas.validate()

 

Remarks for MSXML 6.0

 

In previous versions of MSXML, a schema already in the cache for a given namespace was replaced by the schema from the new location. In MSXML 6.0, when you call this method the declarations are merged with an existing schema with the same namespace. Using this feature, MSXML 6.0 supports "partial schemas". You can load several schemas, all having the same target namespace, into one schema in the schema cache.

 

Calling this method will cause all the schemas imported by the added schema to also be added into the cache as "top-level" schemas.

 

Schema imports are validated "lax" - this means that any namespace or type already added to the schema cache can be referenced by another schema in the cache, even if there is no explicit import in the referencing schema. You need to set validateOnLoad Property to false to avoid issues around the order of calls to this method.

 

The add operation is atomic. All the schemas must be added successfully to the cache, or else none are.

 

MSXML 6.0 has removed support for XDR schemas, whereas XDR is supported in MSXML 3.0 AND MSXML 4.0. If this method is called with an XDR schema, the call will fail.

 

Versioning

 

Implemented in: MSXML 3.0 and later.

 

Valid XHTML 1.0 Transitional