Using DataTable Objects

From Pointui

The DataTable class is extremely important – it provides a generic interface to many of the different types of data that can be retrieved from the device such as Appointments, Contacts, Tasks, Messages, Running Applications, and even Xml documents. Rather than have a different way to access each of these different types of data in script we decided to create the DataTable class which allows access to them all in the same way. It’s very important that you become familiar with how to use DataTable objects as most things you need to do will require you use them.

A DataTable has zero or more Rows. Each Row could represent an entity such as an Appointment, or a Contact – a Row contains details about a single entity. There may be many Appointments in your calendar, so that would mean there would be many Rows in the DataTable – a Row for each Appointment.

Each Row contains zero or more Columns. A Column holds a piece of information about the entity represented by that Row. For instance, if the Row held an Appointment then it would have Columns for “StartTime”, “Location”, “EndTime” etc. But if the Row held a Message then it would have different Columns – for instance “Subject”, “SenderName”, “IsUnread” etc.

Most types of data that are exposed through DataTable objects support once only forward navigating of the rows. Generally speaking, random access to rows is not supported. Typically, a DataTable is initialized and moved through to the final row as the following example shows:

	DataTable appts;
 
	//fetch all appointments
	Appointments.GetAppointments(appts);
 
	//go through all appointments
	while (appts.MoveNext())
	{
		//do something with this appointment
	}

Some types of data will support MoveTo(index) to allow random access, and that is documented where applicable.

Typically an entire list of items is requested for a DataTable, and that list is then restricted using SetRestriction() based on a query if necessary. There is no performance hit for requesting the entire set and restricting as long as the restriction occurs before an attempt to navigate the DataTable happens using MoveNext() etc.

DataTable Rows can also be limited by using SetMaxItems().