namedRecordset Method | Internet Development Index |
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> <!-- 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.
<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>
Standards Information
There is no public standard that applies to this method.
Applies To
APPLET, XML, OBJECT
See Also
Using a Data Source Object that Exposes Multiple Data Members