DataRecordsets.AddFromXML Method

  • Article
Visio Automation Reference

Adds a DataRecordset object to the DataRecordsets collection, and fills the resulting data recordset with data supplied in the form of an XML string.

ms195691.vs_note(en-us,office.12).gif  Note
This Visio object or member is available only to licensed users of Microsoft Office Visio Professional 2007.

Version Information
 Version Added:  Visio 2007

Syntax

expression.AddFromXML(XMLString, AddOptions, Name)

expression   An expression that returns a DataRecordsets object.

Parameters

Name Required/Optional Data Type Description
XMLString Required String An XML string that conforms to the Microsoft ActiveX® Data Objects (ADO) classic XML schema and that describes the data you want to import.
AddOptions Required Long Options that determine properties of the data recordset to add. A combination of one or more enumerated value from VisDataRecordsetAddOptions. For more information, see Remarks.
Name Optional String Assigns a display name to the DataRecordset object being added.

Return Value
DataRecordset

Remarks

For the XMLString parameter, pass an XML string that conforms to the ADO classic XML schema and that describes the data you want to import. A simple XML string is shown in the example later in this topic.

The AddOptions parameter can be a combination of one or more of the following values from the VisDataRecordsetAddOptions enumeration, which is declared in the Microsoft Office Visio type library. The default is zero (0), which specifies that none of the options be set.

Constant Value Description

visDataRecordsetNoExternalDataUI

1

Prevents data in the new data recordset from being displayed in the External Data window.

visDataRecordsetNoAdvConfig

4

Prevents the data recordset from being displayed in the Configure Refresh dialog box.

visDataRecordsetDontCopyLinks

16

Adds a data recordset, but shape-data links are not cut or copied.

Once you assign these values, you cannot change them for the life of the DataRecordset object.

The Name argument is an optional string that lets you assign the data recordset a display name. If you specify that the External Data window display in the Visio UI, the name you pass for this argument appears on the tab of the External Data window that corresponds to the data recordset added.

In contrast with data recordsets created by using the Add or AddFromConnectionFile methods, data recordsets created by using the AddFromXML method are not associated with a DataConnection object.

What's more, Visio never refreshes a data recordset you created by using the AddFromXML method automatically, regardless of the setting of the DataRecordset.RefreshInterval property. To refresh the data in such a data recordset, you must call the DataRecordset.RefreshUsingXML method.

If the AddFromXML method succeeds, it performs the following actions:

  • Creates an DataRecordset object and assigns it the name you specify in the Name parameter. If you do not specify a name, Visio assigns the data recordset the name of the database table that is the source of the data.
  • Maps the data types of the columns of the data source to equivalent Visio data types, while filtering the results to remove data-source columns that cannot be linked to Visio shapes because they have no equivalent Visio data type.
  • Assigns a Visio data-row ID to each row in the data recordset, unless the imported data already contains valid Visio data-row IDs. For more information about Visio data-row IDs, see the DataRecordset.GetDataRowIDs topic.

Example

The following Microsoft Visual Basic for Applications (VBA) macro shows how you can use the AddFromXML method to connect a Visio drawing to data contained in an ADO XML string.

A sample XML string is shown here. When it is passed to the AddFromXML method, this string creates a data recordset that contains one column, named "Cities", and two data rows with entries in that column consisting of city names.

Visual Basic for Applications 
  <xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
xmlns:rs='urn:schemas-microsoft-com:rowset'
xmlns:z='#RowsetSchema'>
<s:Schema id='RowsetSchema'>
<s:ElementType name='row' content='eltOnly' rs:updatable='true'>
<s:AttributeType name='c1' rs:name='Cities'
rs:number='2' rs:nullable='true' rs:maydefer='true' rs:write='true'>
<s:datatype dt:type='string' dt:maxLength='255' rs:precision='0'/>
</s:AttributeType>
<s:extends type='rs:rowbase'/>
</s:ElementType>
</s:Schema>
<rs:data>
<z:row c1='Seattle' />
<z:row c1='Redmond' />
</rs:data>
</xml>

In the following sample code, we pass the AddFromXML method the name of an XML string containing data and the name of a string containing the display name we want to assign to the new data recordset being created.

Visual Basic for Applications 
  Public Sub AddFromXML_Example()

Dim strXML As String
Dim strName As String
Dim vsoDataRecordset As Visio.DataRecordset

strXML = "&lt;xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'" + Chr(10) _
&amp; "xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'" + Chr(10) _
&amp; "xmlns:rs='urn:schemas-microsoft-com:rowset'" + Chr(10) _
&amp; "xmlns:z='#RowsetSchema'&gt;" + Chr(10) _
&amp; "&lt;s:Schema id='RowsetSchema'&gt;" + Chr(10) _
&amp; "&lt;s:ElementType name='row' content='eltOnly' rs:updatable='true'&gt;" + Chr(10) _
&amp; "&lt;s:AttributeType name='c1' rs:name='Cities'" + Chr(10) _
&amp; "rs:number='2' rs:nullable='true' rs:maydefer='true' rs:write='true'&gt;" + Chr(10) _
&amp; "&lt;s:datatype dt:type='string' dt:maxLength='255' rs:precision='0'/&gt;" + Chr(10) _
&amp; "&lt;/s:AttributeType&gt;" + Chr(10) _
&amp; "&lt;s:extends type='rs:rowbase'/&gt;" + Chr(10) _
&amp; "&lt;/s:ElementType&gt;" + Chr(10) _
&amp; "&lt;/s:Schema&gt;" + Chr(10) _
&amp; "&lt;rs:data&gt;" + Chr(10) _
&amp; "&lt;z:row c1='Seattle'/&gt;" + Chr(10) _
&amp; "&lt;z:row c1='Redmond'/&gt;" + Chr(10) _
&amp; "&lt;/rs:data&gt;" + Chr(10) _
&amp; "&lt;/xml&gt;"

strName = "City Names"

Set vsoDataRecordset = ThisDocument.DataRecordsets.AddFromXML(strXML, 0, strName)



End Sub

See Also