DataStore Library: 2.1 Creating a DataStore: Adding Fields

GEOS SDK TechDocs

2 Creating a DataStore

2.2 Adding Records

DataStoreAddField()

Once you've created a new datastore, you can add (non-key) fields at any time with DataStoreAddField() . When adding fields, keep in mind:

• The maximum size of a field name is MAX_FIELD_NAME_LENGTH or 40.
• When defining fields, note the difference between FieldType and FieldCategory . FieldType specifies the type of data stored in the field, such as DSFT_STRING; FieldCategory defines what type of information that data represents, such as a phone number (FC_TELEPHONE). See the C Reference Book for a full list of FieldTypes and FieldCategories .

The following code sample shows how to create a datastore that contains three fields, one of which is the key.

Code Display 9-1 Creating a New DataStore

	/* 
	 * When a new datastore is created, the DataStore Manager
	 * opens a "session" and returns a "session" token
	 */
	word	dsToken;

	/* 
	 * DataStoreCreateParams contains information about
	 * the new datastore, such as key field(s) and access level
	 */
	DataStoreCreateParams	params;

	/*
	 * FieldDescriptor contains information about
	 * a field, such as its name and type
	 */
	FieldDescriptor	field;

	/*
	 * This example will be an "Exchange Rate" datastore with three fields
	 */
	static TCHAR dsName[] = "Exchange Rates";
	static TCHAR field1[] = "country";
	static TCHAR field2[] = "currency";
	static TCHAR field3[] = "exchange rate";

	/*
	 * Define the "country" field; this will become the key field
	 */
	field.FD_name = field1;
	field.FD_data.FD_type = DSFT_STRING;
	field.FD_data.FD_category = FC_NAME;
	field.FD_data.FD_flags = 0;	/* use ascending sort order */

	/*
	 * Set the parameters for the new DataStore file:
	 *   - add a timestamp field (this becomes the first field)
	 *   - define the key field (the key cannot be changed later)
	 *   - designate which object is to receive notifications
	 * 	when the DataStore is changed
	 */
	params.DSCP_name = dsName;
	params.DSCP_flags = DSF_TIMESTAMP;
	params.DSCP_keyList = &field; /* "country" field defined above */
	params.DSCP_keyCount = 1;
	params.DSCP_notifObject = oself; /* "oself" refers to the object handling
			this message; in this case, it is the process object */
	params.DSCP_openFlags = 0; /* make the datastore sharable between apps */

	/* 
	 * Now create the new datastore file. If it is successfully created,
	 * add the additional fields.
	 */
	if(DataStoreCreate(&params, &dsToken) == DSE_NO_ERROR)
	{
		/* 
		 * DataStoreAddField() returns the FieldID of the newly
		 * created field to the passed FieldID variable (i.e., fid).
		 */

		FieldID		fid;

		/* add currency field */
		field.FD_name = field2;
		field.FD_data.FD_type = DSFT_STRING;
		field.FD_data.FD_category = FC_NONE;
		field.FD_data.FD_flags = 0;	/* use ascending sort order */
		DataStoreAddField(dsToken, &field, &fid);

		/* add exchange rate field */
		field.FD_name = field3;
		field.FD_data.FD_type = DSFT_FLOAT;
		field.FD_data.FD_category = FC_NONE;
		field.FD_data.FD_flags = 0;	/* use ascending sort order */
		DataStoreAddField(dsToken, &field, &fid);
	}

Below is a diagram of the "Exchange Rates" datastore created in the above code example. The following section discusses how to add records to the datastore.

Note that fields of type DSFT_FLOAT expect data of type FloatNum (a special GEOS data type that differs from the standard C float type; see the Math chapterfor additional information on FloatNum s).

GEOS SDK TechDocs

2 Creating a DataStore

2.2 Adding Records