Cloning ClientDatSet Cursors

Abstract: When you clone a ClientDataSet's cursor, you create not only an additional pointer to a shared memory store, but also an independent view of the data. This article shows you how to use this important capability.

If you have been following this series, you are no doubt aware that I am a
huge fan of ClientDataSets. Indeed, I feel like I haven't stopped smiling since
Borland added them to the Professional edition of their RAD (rapid application
development) products, including Delphi, Kylix, and C++ Builder. The
capabilities that ClientDataSets can add to an application are many. But of all
the features made available in ClientDataSets, I like cloned cursors the most.

This is the tenth article in this series, and you might be wondering why I've
waited until now to discuss cloning cursors. The answer is rather simple. The
full power of cloned cursors is not obvious until you know how to navigate,
edit, filter, search, and sort a ClientDataSet's data. In some respects, the
preceding articles in this series have been leading
up to this one.

Normally, the
data that you load into a client dataset is retrieved from another dataset or
from a file. But
what do you do when you need two different views of essentially the same data?
One alternative is to load a second copy of the data into a second ClientDataSet.
This approach, however, results in an unnecessary increase in network traffic
(or disk access) and places redundant data in memory. In some cases, a better
option is to clone the cursor of an already populated ClientDataSet. When you
clone a cursor, you create a second, independent pointer to an existing
ClientDataSet's memory store, including Delta (the change log). Importantly, the cloned ClientDataSet has an
independent current record, filter, index, provider, and
range.

It is difficult to appreciate the power of cloned cursors without actually
using them, but some examples can help.
Previously you learned that the data held by a ClientDataSet is stored entirely
in memory. Imagine that you have loaded 10,000 records into a ClientDataSet, and
that you want to compare two separate records in the ClientDataSet programmatically. One approach is
locate the first record and save some of its data into local variables. You can
then locate the second record and compare the saved data to that in the
second record. Yet another approach is to load a second copy of the data in
memory. You can then locate the first record in one ClientDataSet, the second
record in the other ClientDataSet, and then directly compare the two record.

A third approach, and one that has advantages over the first two, is to
utilize the one
copy of data in memory, and clone a second cursor onto this memory store.
The cloned cursor acts is if it were a second copy of the data in memory, in
that you now have two cursors (the original and the clone), and each can point
to a different record. Importantly, only one copy of the data is stored in memory,
and the cloned cursor provides a second, independent pointer into it. You can
then point the original cursor to one record, the cloned cursor to the other,
and directly compare the two records.

Here's another example. Imagine that you have a list of customer invoices stored in
memory using a ClientDataSet. Suppose
further that you need to display this data to the end user using two different
sort orders, simultaneously. For example, imagine that you want to use one
DBGrid to display this data sorted by customer account number, and another
DBGrid to display this data by invoice date. While your first inclination might
be to load the data twice, using two ClientDataSets, a cloned cursor performs
the task much more efficiently. After loading the data into a single
ClientDataSet, a second ClientDataSet is used to clone the first. The
first ClientDataSet can be sorted by customer account number, and the second can
be sorted by invoice date. Even though the data appears in memory only once,
each of the ClientDataSets contain a different view.

How to Clone a ClientDataSet

You clone a ClientDataSet's cursor by invoking the CloneCursor method. This method has the following syntax:

When you invoke CloneCursor, the first argument is
an already active ClientDataSet that points to the memory store you want to work
with.
The second parameter, Reset, is used to either keep or discard the original
ClientDataSet's view. If you pass a value of False, the
values of the IndexName (or IndexFieldNames), Filter, Filtered, MasterSource,
MasterFields, OnFilterRecord, and ProviderName properties are set to
match that of the source client dataset. Passing True in the second parameter resets these properties to
their default values. (A special case with respect to filters is discussed
in the following section.)

For example, if you invoke CloneCursor, passing a value of True in the
second parameter, the cloned ClientDataSet's IndexFieldNames property
will contain an empty string, regardless of the value of the IndexFieldNames property of
the original ClientDataSet. To put this another way, the cloned cursor may or
may not start out with similar properties to the ClientDataSet it was cloned
from, depending
on the second parameter.

You include the third, optional parameter, passing a value
of True, typically in conjunction with a Reset value of False. In this
situation, the properties of the cloned cursor match that of the original
dataset, but may not actually be valid, depending on the situation. In most
cases, a call to CloneCursor only includes the first two parameters.

Although the cloned cursor may not share many view-related
properties with the ClientDataSet it was cloned from, it may present a view that
nearly matches the original. For example, the current record of a cloned cursor
is typically the same record that was current in the original. Similarly, if a
ClientDataSet uses an index to display records in a particular order, the
clone's natural order will match the indexed view of the original, even though
the IndexName or IndexFieldNames properties of the clone may be empty.

This view duplication also applies to ranges. Specifically,
if you clone a ClientDataSet that has a range set, the clone will
employ that range, regardless of the values you pass in the second and third parameters.
However, you can easily change that range, either by setting a new range, or
dropping the range by calling the ClientDataSet's CancelRange method. These
ranges are independent, however, in that each ClientDataSet pointing to a common
memory store can have a different range, or one
can have a range and the other can employ no range.

In general, I think it is a good idea to make few
assumptions about the view of a cloned cursor. In other words, your safest bet
is to clone a cursor passing a value of True in the Reset formal parameter. If
you pass a value of False in the Reset parameter, I suggest that you insert a
comment or Todo item into your code, and document how you expect the view of the
clone to appear. Doing so will help you fix problems that could potentially be
introduced if future implementations of the CloneCursor method change the view
of the clone.

A single ClientDataSet can be cloned any number of times, creating many
different views for the same data store. Furthermore, you can clone a clone to
create yet another pointer to the original data store. You can even clone the
clone of a clone. It really does not matter. There is a single data store, and a
ClientDataSet associated with it, whether it was created by cloning or not, points
to that data store.

Here is another way to think of this. Once a ClientDataSet is cloned, the clone and the original have
equal status, as far as the memory store is concerned. For example, you can load one ClientDataSet with data, and
then clone a second ClientDataSet from it. You can then close the original
ClientDataSet, either by calling its Close method or setting its Active property
to False. Importantly, the clone will remain open. To put this another way, so
long as one of the ClientDataSets remain open, whether it was the original
ClientDataSet used to load the data or a clone, the data and change log remain
in memory.

Cloning a Filtered ClientDataSet: A Special Case

Similar to cloning a ClientDataSet that uses a range, there
is an issue with cloning ClientDataSets that are filtered. Specifically, if you
clone a ClientDataSet that is currently being filtered (its Filter property is
set to a filter string, and Filtered is True), and you pass a value of False (no
reset) in the second parameter of the CloneCursor invocation, the cloned
ClientDataSet will employ the filter also. However, unlike when a cloned cursor
has a range, which can be canceled, the cloned cursor will necessarily be
filtered. In other words, in this situation, the clone can never cancel the
filter it gets from the ClientDataSet it was cloned from. (Actually, you can
apply a new filter to the filtered view, but that does not cancel the original
filter. It merely adds an additional filter on top of the original filter.)

This effect does not occur when Filter is set to a filter
expression, and Filtered is set to False. Specifically, if Filter is set to a
filter expression, and Filtered is False, cloning the cursor with a Reset value
of False will cause the cloned view to have a filter expression, but it will not
be filtered. Furthermore, you can set an alternative Filter expression, and set
or drop the filter, in which case the clone may include more records than the
filtered ClientDataSet from which it was cloned.

The discrepancy between the way a non-reset clone works with
respect to the Filtered property is something that can potentially cause major
problems in your application. Consequently, I
suggest that you pass a value of True in the Reset formal parameter of
CloneCursor if you are cloning an actively filtered ClientDataSet. You can then
set the filter on the clone, in which case the filters will be completely independent.

The Shared Data Store

The fact that all clones share a common data store has some important
implications. Specifically, any changes made to the common data store directly
affects all ClientDataSets that use it. For example, if you delete a record using a cloned cursor,
the record instantly appears to be deleted from all ClientDataSets pointing to
that same store and an associated record appears in the change log (assuming
that the public property LogChanges is set to True, its default value). Similarly,
calling ApplyUpdates from any of the ClientDataSets attempts to apply the
changes in the change log. In addition, setting one of the ClientDataSet's Readonly
property to True prevents any changes to the data from any of its associated
ClientDataSets.

Note that the documentation states that passing a value of True in the second
parameter of CloneCursor will cause the clone to employ the default ReadOnly
property, rather than the ReadOnly value of the ClientDataSet that is being
cloned. Nonetheless, setting ReadOnly on a ClientDataSet to True makes the data
store readonly, which affects all ClientDataSets pointing to that data store.

Likewise, if you have at least one change in the change log, calling
RevertRecord, or even CancelChanges, affects the single change log (represented
by the Delta property). For example, if you deleted a record from a cloned
ClientDataSet, it will appear to be instantly deleted from the views of all the
ClientDataSets associated with the single data store. If you then call
UndoLastChange on one of the ClientDataSets, that deleted record will be removed
from the change log, and will instantly re-appear in all of the associated
ClientDataSets.

Cloning Examples

Cloning a cursor is easy, but until you see it in action it is hard to really
appreciate the power that cloned cursors provide. The following examples are
designed to give you a feel for how you might use cloned cursors in your
applications.

Creating Multiple Views of a Data Store

This first example, CloneAndFilter, shows how you can display many different views of a common
data store using cloned cursors. You can download this project from Code Central
by clicking here.. The following is the main form of this application, which
permits you to select the file to load into a ClientDataSet and then clone.

Once you click the button labeled Load and Display, an instance of the
TViewForm class is created, and the selected file is loaded into a ClientDataSet
associated with this class. The following is how the instance of the TViewForm
looks when the customer.cds file is loaded into the ClientDataSet.

If you have been following this series, you will recognize this form as being
similar to the one I used to demonstrate filters and ranges. I used this form
here, of course, so that you can apply filters, set ranges, change indexes, and
edit and navigate records, and then see what influence these setting have on a
clone of this view.

As you can see from the preceding form, there are two buttons associated with
cloning a cursor. The first, labeled CloneCursor: Reset, will call CloneCursor
with a value of True passed in the second parameter. The following is the
OnClick event handler associated with this button.

When you click CloneCursor: Reset, an instance of
the TViewForm class is created, and the ClientDataSet that appears on this
instance is cloned from the one that appears on Self. The following shows an
example of what this form might look like after a cursor is cloned.

Besides this form's caption, it appears to be a separate view of the
originally loaded file. You can now set filters, ranges, and change the current
record. Importantly, both of the files use the single copy of the data
originally loaded into memory.

The second button associated with cloning is labeled CloneCursor: No Reset.
The following code is associated with the OnClick event handler of this button.

Obviously, the only difference between this method
and the preceding one is the
value passed in the second parameter of the call to CloneCursor.

Unfortunately, the static nature of the screenshots in this article do little
to demonstrate what is going on here. I urge you to either create your own
demonstration project, or to download this project, and play with cloned
cursors for a while. For example, create three clones of the same cursor, and
then close the original TViewForm instance. Then, with several of the TViewForm
instances displayed, post a change to one of the records. You will notice that
all instances of the displayed form will instantly display the updated data.
Next, undo that change by clicking the button labeled Undo Last Change (try
doing this on a form other than the one you posted the change on).

Here's another thing to try. Clone several cursors and then delete a record
from one of the visible forms. This record will immediately disappear from all
forms. Then, click the button labeled Empty Change Log (again, it does not
matter on which form you click this button). The deleted record will instantly
reappear on all visible forms.

Self-Referencing Master-Details

Most database developers have some experience create master-detail views of
data. This type of view, sometimes also called a one-to-many view or a
parent-child view, involves displaying the zero or more records from a detail
table that are associated with the currently selected record in a master table. You
can easily create this kind of view using the MasterSource and MasterFields
properties of a ClientDataSet, given that you have two tables with the
appropriate relationship (such as Borland's sample customer.cds and orders.cds
files).

While most master-detail views involve two tables, what do you do if you want to create
a similar effect using a single table. In other words, what if you want to
select a record from a table and display other related records of that same
table in a separate view.

Sound weird? Well, not really. Consider Borland's
sample file items.cds. Each record in this file contains an order number, a part
number, the quantity ordered, and so forth. Imagine that when you select a
particular part associated with an given order you want to also see, in a
separate view, all orders from this table in which that same part was ordered. In this example,
all of the data resides in a single table (items.cds).

Fortunately, cloned cursors give you a powerful way of displaying
master-detail relationships within a single table. This technique is
demonstrated in the MasterDetailClone project, which can be downloaded form Code
Central by clicking here..

The main form of this running project can be seen in the following figure.
Notice that when a record associated with part number 12306 is selected (in this
case, for order number 1009), the detail view, which appears in the lower grid
on this form, displays all orders that include part number 12306 (including
order number 1009).

This form also contains a checkbox, which permits you to either include or
exclude the current order number from the detail list. When this checkbox is not
checked, the current order in the master table does not appear in the detail, as
shown in the following figure.

In this project, the detail view is created using a cloned cursor of the
master table (ClientDataSet1) from the OnCreate event handler of the main form.
The following is the code associated with this event handler.

Once this event handler confirms that the file name
associated with ClientDataSet1 is valid, there are four steps that are taken
that contribute to the master-detail view. The first step is that ClientDataSet1
is opened, which must occur prior to cloning the cursor.

The second step is that an OnDataChange event handler, which creates the
detail view, is assigned to DataSource1. This is the DataSource that points to
ClientDataSet1. Once this assignment is made, the detail table view is updated
each time OnDataChange is invoked (which occurs each time a change is made to a
field in ClientDataSet1, as well as each time ClientDataSet1 arrives at a new
current record).

The third operation performed by this event handler is the cloning of the
detail table cursor, assigning an appropriate index, and setting the cloned
cursor's Filtered property to True. In this project, the order of steps two and
three are interchangeable.

The forth step is to invoke the OnDataChange event handler of DataSoure1.
This invocation causes the cloned cursor to display its initial detail view.

As must be obvious from this discussion, the OnDataChange event handler
actually creates the detail view. The following is the code associated with this
event handler.

The first line of code in this event handler obtains
a reference to the part number field of ClientDataSet1. The value of this field
is then used to create a range on the cloned cursor. This produces a detail view that includes all
records in the clone whose part number matches the part number of the current
master table record. The remainder of this event handler is associated with the
inclusion or exclusion of the order for the master table's current record from
the detail table. If the Include Current OrderNo checkbox is not checked, a
filter that removes the master order number is assigned to the cloned cursors
Filter property (remember that Filtered is set to True). This serves to suppress
the display of the master table's order number from the detail table.
If Include Current OrderNo is checked, an empty string is assigned to the
clone's Filter property.

That last piece of interesting code in this project is associated with the
OnClick event handler of the Include Current OrderNo checkbox. This code, shown
in the following method, simply invokes the OnDataChange event handler of DataSource1 to
update the detail view.

Although this project is really quite simple, I think
the results are nothing short of fantastic.

Deleting a Range of Records

This third, and final example further demonstrates how creative use of a
cloned cursor can provide you with an alternative mechanism for performing a
task. In this case, the task is to delete a range of records from a ClientDataSet.

Without using a cloned cursor, you might delete a range of records from a
ClientDataSet by searching for records in the range and deleting them, one by one.
Alternatively, you might set an index and use the SetRange method to filter the
ClientDataSet to include only those records you want to delete, which you then
delete, one by one.

Whether you use one of these approaches, or some similar technique,
your code might also need to be responsible for restoring the pre-deletion view
of the ClientDataSet, in particular if the ClientDataSet was being displayed in
the user interface. For example, you would probably what to note the current
record before you begin the range
deletion, and restore that record as the current record when done (so
long as the previous current record was not one of those that was deleted).
Similarly, if you had to switch indexes in order to perform the deletion, you
would likely want to restore the previous index.

Using a cloned cursor to delete the range provides you with an important
benefit. Specifically, you can perform the deletion using the cloned cursor
without having to worry about the view of the original ClientDataSet. Specifically, once
you clone the cursor, you perform all changes to the ClientDataSet's view on the
clone, leaving the original view undisturbed.

The
following is the CDSDeleteRange function found in the CDSDeleteRange project,
which you can download from Code Central by clicking here.

This function begins by creating a temporary ClientDataSet, which is cloned
from the ClientDataSet passed to the function in the first parameter. The clone
is then indexed and filtered using a range, after which all records in the range
are deleted.

The following figure shows the running CDSDeleteRange project. This figure
depicts the
application just prior to clicking the button labeled Delete Range. As you can
see in this figure, the range to be deleted includes all records where the State
field contains the value HI.

While this example project includes only one field in the range, in practice
you can have up to as many fields in the range as there are fields in the
current index. For more information on SetRange, see "Searching a
ClientDataSet," or refer to the SetRange entry in the online documentation.

The following is the code associated with the OnClick event handler of the
button labeled Delete Range. As you can see, the deletion is performed simply by
calling the CDSDeleteRange

The following figure shows this same application immediately following the
deletion of the range. Note that because the deletion was performed by the
clone, the original view of the displayed ClientDataSet is undisturbed, with the
exception, of course, of the removal of the records in the range. Also, because
operations performed on the data store and change log are immediately visible to
all ClientDataSets using a shared in-memory dataset, the deleted records
immediately disappear from the displayed grid, without requiring any kind of
refresh.

I have to admit, I really like this example. Keep in mind, however, that the
point of this example is not about deleting records. It is that a cloned cursor provided an
attractive alternative mechanism for performing the task.

About the Author

Cary Jensen is President of Jensen Data Systems, Inc., a Texas-based training
and consulting company that won the 2002 Delphi Informant Magazine Readers
Choice award for Best Training. He is the author and presenter for Delphi
Developer Days (www.DelphiDeveloperDays.com), an information-packed Delphi
(TM) seminar series that tours North America and Europe, and Delphi Developer
Days Power Workshops, focused Delphi (TM) training. Cary is also an
award-winning, best-selling co-author of eighteen books, including Building
Kylix Applications (2001, Osborne/McGraw-Hill), Oracle JDeveloper (1999, Oracle
Press), JBuilder Essentials (1998, Osborne/McGraw-Hill), and Delphi In Depth
(1996, Osborne/McGraw-Hill). For information about onsite training and
consulting you can contact Cary at cjensen@jensendatasystems.com, or visit his
Web site at www.JensenDataSystems.com.

Click here for a
listing of upcoming seminars, workshops, and conferences where Cary Jensen is
presenting.