The Properties, Methods, and Events of XML DSOs

The Properties, Methods , and Events of XML DSOs

In the example at the beginning of this chapter, we saw that you can use recordset methods such as moveFirst , moveLast , moveNext , and movePrevious to move around in a recordset. I'll make that more systematic now. In particular, the recordset object in an XML DSO has these properties:

absolutePage The page where the current record is
absolutePosition The position in a recordset of the current record
BOF True if the current record position is before the first record
cacheSize The number of records from a recordset object that are cached locally
cursorLocation The location of the cursor for the recordset
cursorType The type of database cursor used
editMode Specification of whether editing is in progress
EOF True if the current position is after the last record
lockType The type of database locking in force
maxRecords The maximum number of records to return to a recordset from a query
pageCount The number of pages of data the recordset contains
pageSize The number of records that make up one page
recordCount The number of records in the recordset
state The state of the recordset ( open or closed)
status The status of the current record
stayInSync Specification of whether a hierarchical recordset should remain in contact with the data source

Here are the methods of the recordset objects inside XML DSOs:

addNew Adds a new record to the recordset.
cancel Cancels execution of a pending Execute or Open request.
cancelUpdate Cancels a pending update operation.
clone Creates a copy of the recordset.
close Closes a recordset.
delete Deletes the current record (or group of records).
find Searches the recordset (although the Structured Query Language syntax required here is not supported by Internet Explorer yet).
getRows Reads records and stores them in an array.
getString Gets the recordset as a string.
move Moves the position of the current record.
moveFirst moveLast , moveNext , movePrevious Let you navigate to various positions in the recordset.
nextRecordSet Clears the current recordset object and returns the next recordset. Used with hierarchical recordsets.
open Opens a database.
requery Re-executes the query that created the recordset.
save Saves the recordset in a file.
supports Indicates the features supported by the recordset. You must pass long integer values that correspond to the various ADO methods, as defined in the Microsoft ADO documentation. For example passing this method a value of 0x1000400 ( 0x specifies a hexadecimal value) returns a value of true , indicating that the record set supports the addNew method; passing a value of 0x10000 returns a value of false , indicating that the record set does not support the updateBatch method.

XML DSOs also have a number of events that you can handle. (Recall that we saw how to handle XML document events in Internet Explorer at the end of the previous chapter.) Here they are:

onCellChange Happens when the data in a bound control changes and the focus leaves that cell
onDataAvailable Happens each time a batch of data is downloaded
onDatasetChanged Happens when the data set was changed
onDatasetComplete Happens when the data is downloaded and ready for use
onReadyStateChange Happens when the ReadyState property changes
onRowEnter Happens when the a new record becomes the current one
onRowExit Happens just before exiting the current record
onRowsDelete Happens when a row is deleted
onRowsInserted Happens when a row is inserted

To let the user navigate around in the recordset created from ch08_03.xml, I'll add the same buttons we saw in the earlier HTML example, using methods such as customers.recordset.moveNext() to navigate, like this:

Listing ch08_04.html

 <HTML>     <HEAD>         <TITLE>Single Record Binding Using XML Data Islands</TITLE>     </HEAD>     <XML SRC="ch08_03.xml" ID="customers"></XML>     <BODY>         <CENTER>             <H1>                 Single Record Binding Using XML Data Islands             </H1>             Name: <INPUT TYPE="TEXT" DATASRC="#customers"                 DATAFLD="NAME" SIZE=10>             <P>             Customer ID: <INPUT TYPE="TEXT" DATASRC="#customers"                 DATAFLD="CUSTOMER_ID" SIZE=5>             <P>             Purchase date: <SPAN DATASRC="#customers"                 DATAFLD="PURCHASE_DATE"></SPAN><P>             Product: <SPAN DATASRC="#customers" DATAFLD="PRODUCT_NAME"></SPAN>             <P>             Department: <SELECT DATASRC="#customers"                 DATAFLD="DEPARTMENT" SIZE=1>             <OPTION VALUE="Meat">Meat             <OPTION VALUE="Produce">Produce             <OPTION VALUE="Frozen">Frozen             </SELECT>             <P>  <BUTTON ONCLICK="customers.recordset.moveFirst()" >   &lt;&lt;   </BUTTON>   <BUTTON ONCLICK="if (!customers.recordset.BOF)   customers.recordset.movePrevious()" >   &lt;   </BUTTON>   <BUTTON ONCLICK="if (!customers.recordset.EOF)   customers.recordset.moveNext()" >   &gt;   </BUTTON>   <BUTTON ONCLICK="customers.recordset.moveLast()">   &gt;&gt;   </BUTTON>  </CENTER>     </BODY> </HTML>

You can see this page in Figure 8-2, where you see the fields of the current record displayed in bound HTML elements. The user can click the buttons in the page to navigate through the recordset.

Figure 8-2. Using data binding to display an XML document in Internet Explorer.

graphics/08fig02.gif

As you can see in the previous list, there's a lot more you can do with a recordset than just navigate through the recordset. For example, it's often useful to access the individual fields in a record. Say that you wanted to get the value in the CUSTOMER_ID field of the current record in the DSO; you can use the expression customers.recordset("CUSTOMER_ID") to do that.

Accessing Data

You might note how much easier accessing data in recordset fields is than using DOM methods, such as nextChild and lastSibling , to navigate a node tree. If you can treat an XML document as a database, it can make life a good deal easier for you.

I'll access individual fields in records now in an example to make this concrete. In this case, I'll loop over all the records in the database (which I can do with a while loop, looping until the recordset's EOF property is true ) and display the customer name, the item purchased, and what department the purchase was made in. Here's what the code looks like:

Listing ch08_05.html

 <HTML>     <HEAD>         <TITLE>             Accessing individual data fields         </TITLE>         <XML ID="customer" SRC="ch08_03.xml"></XML>         <SCRIPT LANGUAGE="JavaScript">             function viewData()             {                 while (!customer.recordset.EOF) {                     div1.innerHTML +=                     customer.recordset("NAME") +                     " bought " +                     customer.recordset("PRODUCT_NAME") +                     " from the " +                     customer.recordset("DEPARTMENT") +                     " department.<BR>"                     customer.recordset.moveNext()                 }             }         </SCRIPT>     </HEAD>     <BODY>         <CENTER>             <H1>                 Accessing individual data fields             </H1>         </CENTER>         <FORM>             <CENTER>                 <INPUT TYPE="BUTTON" VALUE="View data"                     ONCLICK="viewData()">             </CENTER>         </FORM>         <DIV ID="div1">         </DIV>     </BODY> </HTML>

You can see this page in operation in Figure 8-3. As you can see there, the data from the individual fields in the various records has been assembled and displayed.

Figure 8-3. Accessing individual data fields.

graphics/08fig03.gif

Besides working with single records as we have up to this point, you can work with all the data in an XML document at once when you bind it to a table.