SimpleDataset object

   title: SimpleDataset object

platform: Win32; all versions of SE

  source: #include <smdtset.jsh>

A SimpleDataset object is an easy-to-use database-access object that combines database and cursor functionality into a single object.

SimpleDataset is a JavaScript class that combines the concept of a table and a cursor into a single, easy-to-use object. No more than one table may be represented by a SimpleDataset, so inserting items into the dataset doesn't require a target table to be specified. SQL is not needed to use a SimpleDataset and all operations can be performed through simple method calls.

When a SimpleDataset is created, it initially contains all of the rows ("records") in the specified table. The find() method allows this set to be reduced to only those records that match specified templates.

A SimpleDataset has the notion of the "current record". This is the record that SimpleDataset operations will affect. When the SimpleDataset is first created, the current record is the record "before" the first record, and is thus undefined.

Use the firstRecord(), lastRecord(), nextRecord(), and prevRecord() methods, to step through the records in the SimpleDataset. The current record is returned by currentRecord(). The objects returned by these routines have one property for each of the current record's fields.

The current record can be deleted using deleteRecord(). All items in the dataset can be deleted by deleteAll().

Records can be inserted into the table of the SimpleDataset by insertRecord(). The "current" record can be replaced by a specified record using replaceRecord().

A Cursor object representing the SimpleDataset can be obtained by using the cursor() method. It may be necessary to use this to perform more powerful operations on the dataset.

Although the SimpleDataset can be closed through its close() method, it is automatically closed when the object goes out of scope.

Using the SimpleDataset object, the following five-line script can be used to print out the contents of a database:

function print_all(db, table, user, passwd)

{

   var ds = new SimpleDataset(db, table, user, passwd);

   while(var rec = ds.nextRecord())

      for(var prop in rec)

         Screen.writeln(prop + " = " + rec[prop]);

   ds.close();

}

SimpleDataset instance methods