Making the move...

[Rob Cozens]

Hi Geoff ,

> Wow -- so what does this do?
>

 From Serendipity Reference:

 >>

The findSDBRecord command checks for the existence & locked/unlocked 
status of a record with the record type and key specified in line 1 of 
sdbBuffer.  It can also be used to unlock a record that was previously 
locked but not changed or to return a count of the number of records 
with certain field contents.

findSDBRecord is undoubtedly the most complex, but also the most 
powerful, SDB command.  It is the only SDB command that will retrieve 
information from multiple records in a single call.  As such, it is 
ideally suited to retrieve specified fields from a range of records for 
reporting or analysis.

exactKey (boolean) defaults to true, in which case findSDBRecord 
returns card id "0" if the exact key is not in the database; otherwise 
findSDBRecord will return the id for the record with the closest higher 
key of the specified record type.

If fieldDelimiter is empty findSDBRecord simply returns the Revolution 
card id of the record in word 4 of the result.  If fieldDelimiter is 
not empty, itemList contains a list of field references (one per line) 
to retrieve.  A field reference can take two forms:

* a number that resolves to the field's ordinal position in the record 
(0 = the record key)
* an SDB field reference ([Record Type]&":"&[dataname]), which the SDB 
handlers will resolve to a field ordinal.

These two forms of reference can be used interchangably EXCEPT for 
record types that have no Dictionary definition in the database.

findSDBRecord then puts a delimited list of the contents of the fields 
into lines 2 to -1 of sdbBuffer.

setPosition (boolean)  defaults to true.

unlockRecord (boolean) defaults to false.  If true and the record was 
locked by this user, it will be removed from the locked record table.

findSDBRecord can be passed search criteria that must be met before a 
record is retrieved, and instructed to search forward or backward from 
the key if the key's record does not meet the search criteria until the 
first acceptable record is found.

searchForward (boolean) determines search direction; default is true 
(forward).

searchCriteria contains one or more lines in the following format:
-- field reference,test,target,and/or
* field reference is the field's ordinal or Data Dictionary name, as 
defibed above.
* tests: "=" ,"<>" ,"in", "not in", "<", ">", "<=", or ">="
* target is the result to which the item is to be compared; it must be 
a value, not a reference to another field in the record
* "and" or "or" is not needed on last line of search criteria

Example search criteria (assumes the field is defined in Record Type, 
"TYPE" as dataname "department"):
		"TYPE:department",>,21,and
		"TYPE:department",<,34
Selects only records where the value of field "department" is between 
22 and 33.

If cutoffKey is not empty, findSDBRecord will discontinue the search 
when it encounters a record with a key > cutoffKey if searching forward 
or < cutoffKey if searching backward; otherwise the search will end 
with the first matching record if recordDelimiter is empty or the 
last/first record if it is not.

If recordDelimiter is empty, findSDBRecord returns information for the 
first matching record it encounters.  If recordDelimiter is not empty, 
findSDBRecord puts empty into sdbBuffer and returns the number of 
records matching the search criteria in word four of the rersult if the 
fieldDelimiter is empty; otherwise it returns the information for each 
matching record found between the key passed in sdbBuffer and cutoffKey 
or the last/first record of the specified record type.  This 
information will be found in lines 2 to -1 of sdbBuffer.  (The 
recordDelimiter is used to delimit individual records.)

Note that findSDBRecord will return a locked record error if the record 
exists but is locked by another user.

<<

Rob Cozens
CCW, Serendipity Software Company

"And I, which was two fooles, do so grow three;
Who are a little wise, the best fooles bee."

from "The Triple Foole" by John Donne (1572-1631)