namedRecordset method

Article
10/13/2015

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

Syntax

*object.*namedRecordset(dataMember, hierarchy)

Parameters

dataMember [in]
Type: String

String that specifies the name of the data member, or an empty string, which indicates the default data member.
hierarchy [in, optional]
Type: VARIANT

Variant of type String that specifies a path to a hierarchical data set.

Return value

Type: Object

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

Standards information

There are no standards that apply here.

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 type="text/javascript">
// 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>
<!-- The CLASSID below does not correspond to a valid object -->
<object classid="clsid:00000000-0000-0000-0000-000000000000"
    id="dsoSpreadSheet" ondatasetcomplete="handle_dscomplete()">
<!-- Bind the table to the named recordset "A1:A7" provided by the
    spreadsheet control -->
<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.

Code example: http://samples.msdn.microsoft.com/workshop/samples/author/databind/nrs.htm

<script type="text/javascript">
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>

Share via