namedRecordset Method

Retrieves the recordset object corresponding to the named data member from a data source object (DSO).

Syntax

oRecordset = object.namedRecordset(sQualifier [, sSubChapter])

Parameters

sQualifier Required. String that specifies the name of the data member, or an empty string, which indicates the default data member.
sSubChapter Optional. String that specifies a path to a hierarchical data set.

Return Value

Object. Returns a recordset, or null if the specified data member or subchapter is unavailable.

Remarks

Valid names for a data member are specific to the DSO implementation. Check the DSO documentation to determine whether it supports named data members and to determine the valid names for those data members.
If null values or empty strings are passed to the namedRecordset method, the default recordset is returned. This is identical to referring to the recordset property directly.
If the second parameter is omitted, the top-level recordset is returned. If the first parameter is omitted but the second parameter is specified, the specified subchapter of the default recordset is returned.

Examples

In this example, the named recordset corresponds to the first seven cells of the first column of a spreadsheet. This example uses the namedRecordset method to traverse a named recordset in the handler for the ondatasetcomplete event of a hypothetical DSO that provides data from a spreadsheet. The name of the recordset corresponds to the value of the qualifier property of the event object.
<SCRIPT>
// Fired when all the data is available
function handle_dscomplete()
{
var oEvent = window.event;
// ignore the notification for the default recordset
if (oEvent.qualifier != "")
{
// get a reference to the named recordset as indicated by the
// qualifier property
var oNamedRS = oEvent.srcElement.namedRecordset(oEvent.qualifier);
// now walk the named recordset
oNamedRS.MoveFirst();
for (int i = 0; i < oNamedRS.RecordCount; i++)
{
var vValue = oNamedRS.Fields(0).value;
oNamedRS.MoveNext();
}
}
}
</SCRIPT>

<OBJECT CLASSID="clsid:00000000-0000-0000-0000-000000000000"
ID="dsoSpreadSheet" ondatasetcomplete="handle_dscomplete()">

<TABLE DATASRC="#dsoSpreadsheet.A1:A7">
<TR><TD><SPAN DATAFLD="A"></SPAN></TD></TR>
</TABLE>
While the XML data source object does not support named data members, it does support subchapters. This example uses the namedRecordset method to access the item subchapter within an XML data set representing a hierarchy of customers, orders, and items. A subset of the data set follows.
<XML ID="xmlCust">
<customers>
<customer>
<lname>Smith</lname>
<fname>John</fname>
<order id="1">
<item>
<name>gyoza</name>
<quantity>12</quantity>
</item>
<item>
<name>bamboo shoots</name>
<quantity>12</quantity>
</item>
</order>
<order id="2">
<item>
<name>tamari</name>
<quantity>100</quantity>
</item>
</order>
</customer>
</customers>
<customer>
<lname>La Croix</lname>
<fname>Jack</fname>
<order id="3">
<item>
<name>bamboo shoots</name>
<quantity>20</quantity>
</item>
<item>
<name>chili paste</name>
<quantity>20</quantity>
</item>
</order>
</customer>
</XML>
The following script uses the namedRecordset method several times. The first call retrieves the recordset corresponding to the default data member. This recordset contains the set of customers. The second call retrieves the recordset corresponding to the set of orders for the current customer. The third call retrieves the recordset corresponding to the set of items contained by the current order for the current customer. The name of each item is compared to the string passed as the first parameter to the GetTotalOf function. If the strings match, the quantity is accumulated and returned to the caller.
<SCRIPT>
function GetTotalOf(sItemName)
{
var iQuantity = 0;
// get the default data member
var oRSCustomers = xmlCust.recordset; // equivalent to xmlCust.namedRecordset("")
oRSCustomers.MoveFirst();
for (var iCust = 0; iCust < oRSCustomers.RecordCount; iCust++)
{
// get the set of orders for each customer
var oRSOrder = xmlCust.namedRecordset("", "order");
oRSOrder.MoveFirst();
for (var iOrder = 0; iOrder < oRSOrder.RecordCount; iOrder++)
{
// get the set of items for each order
var oRSItems = xmlCust.namedRecordset("", "order.item");
oRSItems.MoveFirst();
for (var iItem = 0; iItem < oRSItems.RecordCount; iItem++)
{
if (oRSItems.Fields("name").value == sItemName)
{
iQuantity += parseInt(oRSItems.Fields("quantity").value);
}
oRSItems.MoveNext();
}
oRSOrder.MoveNext();
}
oRSCustomers.MoveNext();
}
return iQuantity;
}
var iTotal = GetTotalOf("tamari"); // returns 20
iTotal = GetTotalOf("bamboo shoots"); // returns 40
</SCRIPT>
This feature requires Microsoft® Internet Explorer 5 or later. Click the following icon to install the latest version. Then reload this page to view the sample.

Standards Information

There is no public standard that applies to this method.

Applies To

APPLET, XML, OBJECT