keyfile

Top  Previous  Next

keyfile

kfobj=new("keyfile"[,filename$])

 

A keyfile object provides access to a disk file that stores records based on a unique string key.  Keys can be up to 127 characters long.  Records can be of any size and format.  If filename$ is not supplied, a temporary file is created that is erased when the object is destroyed.

 

Properties

chan is a read-only property that stores the underlying channel number that the file is open on.

count is a read-only property that contains the number of records in the keyfile.

filename$ is a read-only property that contains the name of the file being managed.

found is a read-only collection object handle that is filled by methods that find records or return ranges of records from the file.

 

Methods

delete(ky$) removes the record identify by ky$.  If the key doesn't exist, an error occurs.

exists(ky$) returns true (1) if ky$ exists in the file, false(0) otherwise.

find(search$[,nocase[,invert]]) initializes the found collection object, then fills it with keys and records whose records contain the text search$.  If nocase is true (1), then the search is case-insensitive.  If invert is true (1), then records that do not contain search$ are added, rather than those that do.  The function returns the number of records found.

findreg(regex$[,nocase[,invert]]) initializes the found collection object, then fills it with keys and records whose records match the regular expression regex$.  If nocase is true (1), then the search is case-insensitive.  If invert is true (1), then records that do not match regex$ are added, rather than those that do. The function returns the number of records found.

findwhere(whereexpr$,dlm$,quotes) initializes the found collection, then searches records that match the where expression.  For this search, records are assumed to be in delimited format, with the supplied dlm$ value as the delimiter.  If quotes is true (1), then fields are parsed assuming they may be quoted to protect delimiter values in field values.

 

The structure of the where expression is of a Boolean expression using fields, values, comparison operators, parentheses, and AND or OR, using #number syntax to represent field numbers.  All fields are assumed to be string data, but you can use num() to convert strings to numbers, so long as the string is an unpunctuated numeric value.  Here are some examples:

 

#2<>"" - field 2 not null

 

#2="100" and (num(#3)>=0 and num(#3)<10000) - field 2 is "100" and field 3 is between 0 and 10000

keycur$() returns the key of the last accessed key accessed.

keyfirst$() returns the first key in the file in key sequence.

keylast$() returns the last key in the file in key sequence.

keynext$() returns the next key relative to the last key accessed.

keyprev$() returns the previous key relative to the last key accessed.

keyval$(recno) returns the key of the record number specified.  The record number is a sequential value in key order.

range(first$,count[,descending]) initializes the found collection, then fills it with keys and records starting from the key first$, and adding up to count records.  If descending is true (1), then records are returned in reverse key sequence. The number of records found is returned.

range(first,count[,descending]) initializes the found collection, then fills it with keys and records starting from the record number first, and adding up to count records.  If descending is true (1), then records are returned in reverse key sequence. The number of records found is returned.

range(key1$,key2$) initializes the found collection, then fills it with keys and records from the key range provided.  For example, to get all records with keys starting with "100", you might use range("100","100Z").  The two keys do not have to exist in the file.  The number of records found is returned.

read$([ky$]|[recno]) returns a record.  If a key or record number are supplied, the specified record is returned. Otherwise, the next record in ascending key sequence is returned, relative to the last record accessed.  If the key or record number does not exist, an error is generated.

readlock$(ky$[,timeout]) reads and locks the record.  If timeout is provided, then if the record is not available (locked by another task), the system will wait for up to timeout seconds before returning an error.  If the key doesn't exist, or the record is locked, an error is generated.

write(ky$,rec$) writes the record identified by ky$.  If the key already exists, the record is replaced.  If not, it is added.  If the key is locked by another task, an error occurs.