DataStore Library: 5 String Search

GEOS SDK TechDocs

4 Building an Index

6 Enumeration

DataStoreStringSearch()

To do a simple string search (on a specified field or field category), use DataStoreSearchString() . Starting at a specified record number, this routine searches through each record until it finds a match or until it runs out of records to search.

DataStoreSearchString() uses the following parameters:

typedef struct {
	SearchType	SP_searchType;
	RecordNum	SP_startRecord;
	dword	SP_maxRecords;
	FieldID	SP_startField;
	FieldCategory	SP_category;
	TCHAR	*SP_searchString;
	SearchFlags	SP_flags;
} SearchParams;

SP _searchType

Possible flags:

• ST_ALL
  Search all fields of FieldType DFST_STRING.
• ST_FIELD
  Search by FieldID . (Specify the FieldID in SP_startField , explained below.)
• ST_CATEGORY
  Search by FieldCategory . (Specify the FieldCategory in SP_category , explained below.)

SP _startRecord

RecordNum of record to begin search. This routine updates this field with the RecordNum of the last record examined.

SP _maxRecords

Maximum number of records to search. Allows the program to break out of the search if no matches are found. (The search can be continued by incrementing the value of SP_startRecord .) Passing -1 causes the routine to search all records.

SP _startField

FieldID of field to search if SP_searchType is set to ST_FIELD. If you specify a non-string field, the routine will return DSE_BAD_SEARCH_PARAMS.

FieldID of the field to begin the search if SP_searchType is set to ST_CATEGORY. If you specify a field that is not of the specified category, the routine will start with the next field it finds of the specified category.

SP _category

FieldCategory to search if SP_searchTyp e is set to ST_CATEGORY (otherwise this parameter is ignored).

SP _searchString

Null-terminated string to search.

SP _flags

Possible flags:

• SF_BACKWARDS
  Search backwards through the records.
• SF_START_AT_END
  Begin search from first record (going forward) or from last record if SF_BACKWARDS is also passed. If set, SP_startRecord is ignored.
• SF_IGNORE_CASE
  Ignore case when searching.
• SF_NO_WILDCARDS
  Ignore wild card characters.
  
  Many libraries including DataStore support the use of wild card characters for searching. See the Text object chapter for a discussion of wild card searching; also, see /Appl/Datastore/datastore.goc for a code example.
• SF_PARTIAL_WORD
  Treat search string as a substring. For example, if search string is "den," return "gardenia," "dentist," and "garden."

The following example shows how to set up a simple string search on a specified field.

Code Display 9-6 Searching a DataStore

	/* search conditions */
	SearchParams	params;

	/*  Specify search parameters. */
	params.SP_searchType = ST_FIELD; /* search by FieldID */
	params.SP_startRecord = 0; /* start search at first record */
	params.SP_maxRecords = -1; /* search all records until a match is found or 
					there are no more records to search */
	params.SP_startField = 1; /* search "country" field */
	params.SP_searchString = "Albania"; /* string to search for */
	params.SP_flags = SF_IGNORE_CASE; /* ignore case when searching */

	/* Open the datastore. */
	if(DataStoreOpen("Exchange Rates", oself, 0, &dsToken) == DSE_NO_ERROR)
	{
		/* Do the search. */
		if(DataStoreStringSearch(dsToken, &params) == DSDE_NO_ERROR)
		{
			 /*
			  * If a match is found, load the record and get the data
			  * from the "exchange rate" field.
			  * Note:  DataStoreStringSearch() returns the record
			  * number of the last examined record in SP_startRecord.
			  */
			if(DataStoreLoadRecordNum(dsToken, params.SP_startRecord,
							&recordID) == DSDE_NO_ERROR)
			{
				/* variables used for retrieving field data */
				FloatNum		rateBuffer, *pRateBuffer;
				RecordID		recordID;
				MemHandle		dummy;
				word		size;

				pRateBuffer = &rateBuffer;
				size = sizeof(rateBuffer);

				DataStoreGetField(dsToken, "exchange rate", 0,
					(void **)&pRateBuffer, &size, &dummy);
				/*
				  * Do something with the data then 
				  * flush the record from the buffer.
				  */
				DataStoreDiscardRecord(dsToken);
			}
		DataStoreClose(dsToken);
		}
	}

If the routine returns DSE_NO_MORE_RECORDS, it has reached the last record in the file (either the first or last record depending on the direction of the search). If the routine returns DSE_NO_MATCH_FOUND, it did not find a match within the set of records it searched. If it returns DSE_NO_ERROR, it writes the RecordNum of the matching record in SP_startRecord .

The DataStore Library does not implement global searches ( i.e. , searches through multiple datastores), though it is possible to implement this type of search at the application level by opening each datastore file and calling DataStoreStringSearch() on each one.

GEOS SDK TechDocs

4 Building an Index

6 Enumeration