home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 1: Amiga
/
FrozenFish-Apr94.iso
/
bbs
/
alib
/
d9xx
/
d953
/
isam.lha
/
ISAM
/
ISAM.AutoDocs
< prev
next >
Wrap
Text File
|
1993-11-28
|
40KB
|
1,212 lines
===============================================================================
TABLE OF CONTENTS
isam.library/CountISAMRecords
isam.library/CloseISAMFile
isam.library/CreateISAMFile
isam.library/DeleteISAMFile
isam.library/DeleteISAMRecord
isam.library/DeleteISAMRecords
isam.library/GetFirstLastISAMKeyValues
isam.library/ISAMWhy
isam.library/LockISAMFile
isam.library/LockISAMRecord
isam.library/ModifyISAMRecord
isam.library/OpenISAMFile
isam.library/ReadISAMRecord
isam.library/ReadUniqueISAMRecord
isam.library/ReadNextISAMKey
isam.library/ReadNextISAMRecord
isam.library/ReIndexISAMFile
isam.library/ReportISAMStatus
isam.library/SetUpISAMIterationRange
isam.library/SetUpISAMIterationKey
isam.library/SetUpISAMIterationPrefix
isam.library/ShutDownISAM
isam.library/StoreISAMRecord
isam.library/UnLockISAMFile
isam.library/UnLockISAMRecord
isam.library/UnLockAllISAMRecords
===============================================================================
isam.library/CountISAMRecords isam.library/CountISAMRecords
NAME
CountISAMRecords -- count the number of records in an iteration
SYNOPSIS
error = CountISAMRecords ( ISAMHandle, KeyNo, CountMax, Count )
long CountISAMRecords ( ULONG, UWORD, ULONG, ULONG * );
FUNCTION
This function counts the number of records that meet the criteria
of an iteration set up previously by SetUpISAMIteration(Range|Key|
Prefix).
(In effect, the function calls ReadNextISAMKey repeatedly until
ERROR_NO_MORE_RECORDS is returned).
If CountMax is zero, the counting will continue until the last record
meeting the criteria SetUp is found.
If CountMax is not zero, the counting will stop when the count equals
CountMax. (Count will then == CountMax).
NOTES
If no iteration is set up for the specified key, Count will be set to
zero.
When this function finishes counting, it sets up the iteration again
at its starting point. Since the iteration is re-set, it follows that
this function should only be called at the beginning of the iteration,
before any records/keys have been read.
WARNINGS
Keep in mind that if any of the records whose keys match the
iteration are locked by another user, they may change between the
time you Count them and ReadNext them, and may not be in the iter-
ation any more (and may in fact have been deleted), so unless you are
able to lock the file prior to the Count, the number of records you
subsequently ReadNext may NOT match the Count.
This is MUCH faster (and easier) than doing a SetUp/ReadNext loop
just to count records. HOWEVER, if many records are involved, this
will NOT be instantaneous, and other users will be kept waiting. If
counting many records is necessary, and there are always going to be
other users, then it would be preferable to "go the long route" of
doing a SetUp/ReadNext loop to count the records, as other users would
be able to "get in through the cracks" (between ReadNext calls).
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the key upon which an iteration was set.
CountMax - the maximum number of records to count, or zero.
Count - a pointer to the location where the count will be returned.
RESULTS
error - returns OK (#define'd as 0L), or an errorcode.
BUGS
SEE ALSO
SetUpISAMIteration(Range|Key|Prefix), ReadNextISAM(Record|Key)
===============================================================================
isam.library/CloseISAMFile isam.library/CloseISAMFile
NAME
CloseISAMFile -- close an ISAM file
SYNOPSIS
error = CloseISAMFile ( ISAMHandle )
long CloseISAMFile ( ULONG );
FUNCTION
This function closes an ISAM file previously opened by OpenISAMFile.
NOTES
When this function is called, all records in the file locked by the
user will be unlocked, and if the file was locked by the user, it
will be unlocked as well. All iterations set up by the user will
be removed. If the user was the only user, all memory constructs
tracking the file will be freed, the index header written back to the
index file, and the index and data files closed.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
OpenISAMFile
===============================================================================
isam.library/CreateISAMFile isam.library/CreateISAMFile
NAME
CreateISAMFile -- create an ISAM file
SYNOPSIS
error = CreateISAMFile ( SpecsFileName )
long CreateISAMFile ( char * );
FUNCTION
This takes the information describing the ISAM file from the Specs
File named and creates an ISAM file. The Data File will be empty;
the Index File will contain the Index Header.
If the Data and/or Index Files exist already, they will be deleted.
NOTES
The Specs file consists of a minimum of 4 (four) lines:
1. Data File path/name
2. Index File path/name
3. record size
4 key #0 specs
[5. key #1 specs]
[6. key #2 specs]
...
INPUTS
SpecsFileName - null-terminated path/name of the Specs File
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ReIndexISAMFile, ISAM.doc (for full description of Specs File)
===============================================================================
isam.library/DeleteISAMFile isam.library/DeleteISAMFile
NAME
DeleteISAMFile -- Delete an ISAM file
SYNOPSIS
error = DeleteISAMFile ( SpecsFileName )
long DeleteISAMFile ( char * );
FUNCTION
This function deletes an ISAM file, from the information stored in
the Specs File.
NOTES
This deletes both data and index files named in the Specs File.
The Specs File itself is NOT deleted.
INPUTS
SpecsFileName - null-terminated path/name of the Specs File
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/DeleteISAMRecord isam.library/DeleteISAMRecord
NAME
DeleteISAMRecord -- delete an ISAM record
SYNOPSIS
error = DeleteISAMRecord ( ISAMHandle, RecNo )
long DeleteISAMRecord ( ULONG, ULONG );
FUNCTION
This function deletes the specified record from the specified ISAM file.
NOTES
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
RecNo - the record number of a record in the specified ISAM file
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
DeleteISAMRecords
===============================================================================
isam.library/DeleteISAMRecords isam.library/DeleteISAMRecords
NAME
DeleteISAMRecords -- delete a sequence of ISAM records
SYNOPSIS
error = DeleteISAMRecord ( ISAMHandle, KeyNo, Count )
long DeleteISAMRecords ( ULONG, UWORD, ULONG * );
FUNCTION
This function deletes all records matching the criteria previously
established by SetUpISAMIteration(Range|Key|Prefix) for the
specified Key in the specified ISAM File.
This is often used when multiple related files exist. For instance,
an Invoice Header file, and an Invoice Line Items file, with its key
the Invoice Number. To delete an Invoice, one needs to delete both
the Invoice Header record and all Invoice Line Items with that same
Invoice Number. One would set up an iteration on the invoice number
in the Invoice Line Items file, and call this function; then the
Invoice Header record would be deleted.
NOTES
OK will be returned even if no records meet the criteria, or if
SetUp... was not called for the Key in question (the idea being not
to have any records which meet the criteria, if there were none to
begin with, the objective IS achieved).
Any other iterations set up for the specified ISAM file will be
deleted (as a consequence of deleting the first record).
WARNINGS
Deleting all records which meet certain criteria CANNOT be done
by setting up an iteration and repeatedly calling DeleteISAMRecord
from a ReadNextISAM(Key|Record) loop, as the first Delete will kill
the iteration (along with all others for that file). Either this
function or the technique described in IMPLEMENTATION (below) must
be used.
This function will not return until all records meeting the criteria
are deleted. Any other users will be forced to wait. If there
are always other users, then use the technique described in
IMPLEMENTATION.
IMPLEMENTATION
ISAM does the equivilent of ReadNextISAMKey until ERROR_NO_MORE_RECORDS
is returned, storing the record numbers in memory as it does so.
Then it deletes the records from the list in memory.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
KeyNo - the Key Number of a key on which an iteration is set up
Count - a pointer to a variable which will contain the count of
records deleted
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
DeleteISAMRecord
===============================================================================
isam.library/GetFirstLastISAMKeyValues isam.library/GetFirstLastISAMKeyValues
NAME
GetFirstLastISAMKeyValues -- retrieve the first and last key values
for a particular key
SYNOPSIS
error = GetFirstLastISAMKeyValues ( ISAMHandle, KeyNo,
FKeyValue, FRecNo,
LKeyValue, LRecNo )
long GetFirstLastISAMKeyValues ( ULONG, UWORD, void *, ULONG *,
void *, ULONG * );
FUNCTION
This function returns the first and last key values for the specified
key in the specified ISAM File. It also returns the corresponding
record numbers of the first and last key values.
NOTES
IMPLEMENTATION
INPUTS
ISAMHandle
- the ISAM Handle identifying the desired ISAM file
KeyNo - the Key Number of a key of the specified ISAM file
FKeyValue
- a pointer to the area of memory into which the first key
value will be read (Note: this is memory owned by the USER,
not ISAM)
FRecNo
- a pointer to a variable which will contain the record
number of the first key value
LKeyValue
- a pointer to the area of memory into which the last key
value will be read (Note: this is memory owned by the USER,
not ISAM)
LRecNo
- a pointer to a variable which will contain the record
number of the last key value
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/ISAMWhy isam.library/ISAMWhy
NAME
ISAMWhy -- return an Error string corresponding to an Error number
SYNOPSIS
string = ISAMWhy ( ErrNo )
char *ISAMWhy ( long );
FUNCTION
This function returns a string corresponding to an ERROR_ error define.
NOTES
This function does not use the server, and hence may be used when ISAM
is not installed.
INPUTS
ErrNo - an error number
RESULTS
string - a NULL-terminated string containing the "ERROR_" message
corresponding to the error ErrNo, or NULL if ErrNo
is not currently an ISAM error number
BUGS
SEE ALSO
===============================================================================
isam.library/LockISAMFile isam.library/LockISAMFile
NAME
LockISAMFile -- Lock an ISAM file (limit/deny access to other users)
SYNOPSIS
error = LockISAMFile ( ISAMHandle, LockType )
long LockISAMFile ( ULONG, char );
FUNCTION
This function locks the specified ISAM file with the specified lock
type, limiting or denying other users access to it.
NOTES
If the lock type is 'W', then no other user may access the file
or any records in the file in any way. If the lock type is 'R',
then other users may perform Read operations on the file, but may
not make any changes to the file.
Since it is not considered an error to lock an already locked file,
this function may also be used to change the lock type of a locked
file.
If the value ALLFILES is given for ISAMHandle, then an attempt will
be made to lock all of the files that the user has open. Any fail-
ure will result in any files locked by this function being unlocked
again.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file, or
the value ALLFILES (#define'd as 0L)
LockType - 'W' (exclusive) or 'R' (shared)
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
UnlockISAMFile
===============================================================================
isam.library/LockISAMRecord isam.library/LockISAMRecord
NAME
LockISAMRecord -- Lock an ISAM record
SYNOPSIS
error = LockISAMRecord ( ISAMHandle, RecNo, LockType )
long LockISAMRecord ( ULONG, ULONG, char );
FUNCTION
This function locks the specified record in the specified ISAM file,
limiting or denying other users access to to it.
NOTES
If the lock type is 'W', then no other user may access the record
in any way. If the lock type is 'R', then other users may perform
Read operations, but may not make any changes to the record.
Since it is not considered an error to lock an already locked record,
this function may also be used to change the lock type of a locked
record.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
RecNo - the record number of the record to be locked
LockType - 'W' (exclusive) or 'R' (shared)
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
UnLockISAMRecord
===============================================================================
isam.library/ModifyISAMRecord isam.library/ModifyISAMRecord
NAME
ModifyISAMRecord -- replace a record with an altered record
SYNOPSIS
error = ModifyISAMRecord ( ISAMHandle, RecNo, Record )
long ModifyISAMRecord ( ULONG, ULONG, void * );
FUNCTION
This function removes record RecNo from the specified ISAM file,
and replaces it with the specified Record. The record number
remains the same. If any keys are changed, their old key values
are removed from the Index file, and their new key values are then
added.
NOTES
ISAM has no way of knowing how drastically the record might be
changed, so has no way of knowing if the RecNo provided is the
correct one (other than knowing it is outside the acceptable
range or refers to a deleted record). So long as the RecNo
provided is valid, the operation will proceed. If the wrong
RecNo is provided, the old record is gone. Be careful.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
RecNo - the record number of the record to be modified
Record - a pointer to the record to replace that of RecNo
Normally this will be the address of a struct
(example: "&AddrRec" ).
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
StoreISAMRecord
===============================================================================
isam.library/OpenISAMFile isam.library/OpenISAMFile
NAME
OpenISAMFile -- Open an ISAM file
SYNOPSIS
error = OpenISAMFile ( SpecsFileName, LLock, LockType, SaveHead,
ISAMHandle )
long OpenISAMFile ( char *, BOOL, char, BOOL, ULONG * );
FUNCTION
This function opens the ISAM file specified in the Specs File.
NOTES
If LLock is TRUE, an attempt will be made to lock the file.
If another user has the file locked, or has records in the file
locked, this function will fail, with ERROR_FILE_LOCKED or ERROR_
RECORDS_LOCKED, respectively.
If LLock is FALSE, but the file/records are locked, this function
will succeed. Subsequent functions may fail, depending on the
lock type and function.
Certain vital information about the file is stored in the Index File
Header. A duplicate of this header is kept in memory, and it is this
memory-Header that is affected whenever a record is stored, modified
or deleted. If SaveHead is TRUE, this Header will be saved back to
the file each time a record is stored, modified, or deleted. The
index file will therefore be updated more often. A bit more time is
consumed diring those operations. If SaveHead is FALSE, the header
will be saved back to the file only when the file is closed. Of
course, if another user has this file open with SaveHead = TRUE, the
header will be saved whenever THAT user stores/modifies/deletes a
record...
INPUTS
SpecsFileName - null-terminated path/name of the Specs File
LLock - TRUE / FALSE
LockType - 'W' (exclusive) or 'R' (shared)
SaveHead - TRUE / FALSE
ISAMHandle - a pointer to the variable into which the ISAM Handle
identifying the ISAM file will be placed
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/ReadISAMRecord isam.library/ReadISAMRecord
NAME
ReadISAMRecord -- Read an ISAM record
SYNOPSIS
error = ReadISAMRecord ( ISAMHandle, RecNo, LLock, LockType, Record )
long ReadISAMRecord ( ULONG, ULONG, BOOL, char, void * );
FUNCTION
This function reads record RecNo from the specified ISAM file.
If LLock is TRUE, an attempt will be made to lock the record with
lock type LockType.
NOTES
This function is normally called after a series of ReadUnique- or
ReadNext- operations, at which times only certain data were kept,
including the record number. Later, the record numbers alone are
used to read the records again (using this function) to perform some
other action.
Also, records may be read in sequential order (first to last in the
data file) by a loop similar to: for ( ul=0L; ;ul++ ) using "ul" as
the RecNo. Ultimately, ERROR_RECORD_TOO_HIGH will be returned,
indicating the last record has been read.
NOTE: if more records have been deleted then subsequently stored,
there will be "holes" in the data file, and you will encounter them
when attempting to sequentially read the records as described above.
ERROR_DELETED_RECORD will be returned for each "hole" you attempt to
read. Design your code with this in mind, and EXPECT to get this
error if you read the records sequentially.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
RecNo - the record number of the record to be read
LLock - TRUE / FALSE
LockType - 'W' (exclusive) or 'R' (shared)
Record - a pointer to the area of memory into which the record will
be read
NOTE: as with all references to "Record", this is a pointer
to memory owned by the USER, not ISAM.
Normally this will be the address of a struct
(example: "&AddrRec" )
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ReadUniqueISAMRecord, ReadNextISAMRecord
===============================================================================
isam.library/ReadUniqueISAMRecord isam.library/ReadUniqueISAMRecord
NAME
ReadUniqueISAMRecord -- read an ISAM record with a specific key value
SYNOPSIS
error = ReadUniqueISAMRecord ( ISAMHandle, KeyNo, KeyValue, LLock,
LockType, RecNo, Record )
long ReadUniqueISAMRecord ( ULONG, UWORD, void *, BOOL, char,
ULONG *, void * );
FUNCTION
This function reads the record from the specified ISAM File that
has a specified unique key value.
NOTES
ERROR_KEY_NOT_UNIQUE will be returned if key KeyNo is not a unique key.
ERROR_NO_SUCH_RECORD will be returned if there is no record in the
file containing the key value specified.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the key whose value is being sought
KeyValue - the key value being sought
LLock - TRUE / FALSE
LockType - 'W' (exclusive) or 'R' (shared)
RecNo - a pointer to the variable into which the record number of
the record being read will be placed (example: &RecNo )
Record - a pointer to the area of memory into which the record will
be read. Normally this will be the address of a struct
(example: "&AddrRec" ).
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/ReadNextISAMKey isam.library/ReadNextISAMKey
NAME
ReadNextISAMKey -- Read the next key value of an iteration
SYNOPSIS
error = ReadNextISAMKey ( ISAMHandle, KeyNo, RecNo, KeyValue )
long ReadNextISAMKey ( ULONG, UWORD, ULONG *, void * );
FUNCTION
This function reads the next key value of an iteration.
If there are no more records meeting the criteria of the iteration,
then the code ERROR_NO_MORE_RECORDS is returned.
NOTES
Unlike ReadNextISAMRecord, no error is returned if the record RecNo
is locked.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the iteration
RecNo - a pointer to the variable into which the record number of
the record containing the key being read will be placed
(example: &RecNo )
KeyValue - a pointer to the area of memory into which the key value
will be read (Note: this is memory owned by the USER,
not ISAM.
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
SetUpISAMteration(Range|Key|Prefix)
===============================================================================
isam.library/ReadNextISAMRecord isam.library/ReadNextISAMRecord
NAME
ReadNextISAMRecord -- Read the next record of an iteration
SYNOPSIS
error = ReadNextISAMRecord ( ISAMHandle, KeyNo, LLock, Locktype,
RecNo, Record )
long ReadNextISAMRecord ( ULONG, UWORD, BOOL, char, ULONG *, void * );
FUNCTION
This function reads the next record of an iteration.
If there are no more records meeting the criteria of the iteration,
then the code ERROR_NO_MORE_RECORDS is returned.
NOTES
If the record RecNo is locked, the code ERROR_RECORD_LOCKED is
returned, and the record is NOT READ. The iteration is left intact,
and the next call to this function will get the next record (unless
it, too, is locked, etc.)
RecNo will be set even if the record is locked.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the iteration
LLock - TRUE / FALSE
LockType - 'W' (exclusive) or 'R' (shared)
RecNo - a pointer to the variable into which the record number of
the key being read will be placed (example: &RecNo )
Record - a pointer to the area of memory into which the record will
be read. Normally this will be the address of a struct
(example: "&AddrRec" ).
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
SetUpISAMIteration(Range|Key|Prefix)
===============================================================================
isam.library/ReIndexISAMFile isam.library/ReIndexISAMFile
NAME
ReIndexISAMFile -- generate a new index file for a data file
SYNOPSIS
error = ReIndexISAMFile ( SpecsFileName, Counter )
long ReIndexISAMFile ( char *, BOOL );
FUNCTION
This function re-creates an index file for a data file, from the
information stored in the specified Specs File.
NOTES
Any existing index file will be deleted.
This function is usually called when the original index file is
accidentally deleted or becomes corrupt, or when a key length is
changed, or a key is added or removed.
It may also be used to create an ISAM file from a fixed-length
record-seqential data file (run "SeqToISAM" first (see ISAM.doc).
This function CANNOT be used to change a record length, or change
the position or length of any data in the record.
The data file will not be altered, except for a portion of the space
occupied by deleted records. This means that if it is found that the
new specifications are wrong, just change them and ReIndex again.
If Counter is TRUE, a small window is opened on the Workbench screen
showing the count of records being processed. This helps in gaining
an idea of the length of time the re-indexing will take.
So that you don't have to constantly watch the screen, when the
ReIndexing is complete, the screen will flash, and the highest RecNo
processed will remain in the window for 5 seconds, after which the
window will close, and the function will return.
WARNINGS
Changing a repeatable key to a unique key may obviously cause problems.
If a record with a duplicate key value is found for a unique key, NONE
of the keys for that record will be stored, and the record will become
inaccessible, and unlike deleted records, the space taken up in the
data file by records ignored in this way will NOT be reclaimed.
This function will not return until all records are re-indexed.
Any other users will be forced to wait.
This can be a slow process. If the data and index files will fit
into RAM:, place them there. If they must be on floppy, some time
may be gained by having the data and index files on separate disks
(if the system has two floppy drives).
When figuring whether or not you have enough memory/disk space, note
that if you're changing the number or size of keys, the new index
file will DIFFER in size from the old one.
INPUTS
SpecsFileName - null-terminated path/name of the Specs File
Counter - TRUE / FALSE
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ISAM.doc, for information re: changing the record length, or the
position or length of any data in a record
===============================================================================
isam.library/ReportISAMStatus isam.library/ReportISAMStatus
NAME
ReportISAMStatus -- cause a file to be created describing the current
status of the ISAM server
SYNOPSIS
error = ReportISAMStatus ( )
long ReportISAMStatus ( void );
FUNCTION
This function causes the server to create the file RAM:ISAMStatus,
which contains information on the current status of ISAM: how many
users/files, which files for which users, the stack size and largest
stack amount used so far, etc.
NOTES
INPUTS
none
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/SetUpISAMIterationRange isam.library/SetUpISAMIterationRange
NAME
SetUpISAMIterationRange -- set up an iteration to range between two
key values
SYNOPSIS
error = SetUpISAMIterationRange ( ISAMHandle, KeyNo, IterType,
KeyFrom, KeyTo )
long SetUpISAMIterationRange ( ULONG, UWORD, UBYTE, void *, void * );
FUNCTION
This function sets up an iteration to range between two key values
for key KeyNo, for the specified ISAM File.
NOTES
Subsequent ReadNextISAM(Key|Record) calls will result in records
being found with key values ranging between KeyFrom and KeyTo.
The iteration type determines whether the keyvalues will take on
all key values, one key value, or a range of values, and one or both
of the end points (KeyFrom, KeyTo) may be excluded from the range.
Type KeyFrom KeyTo Meaning
---- ------- ----- -------
0 - - ALL key values
1 X - ONE key value
2 - ----> O all key values to KeyTo
3 - ----> X all key values through KeyTo
4 O ----> O all key values after KeyFrom to KeyTo
5 X ----> O all key values from KeyFrom to KeyTo
6 O ----> X all key values after KeyFrom through KeyTo
7 X ----> X all key values from KeyFrom through KeyTo
8 O ----> - all key values after KeyFrom
9 X ----> - all key values from KeyFrom
where: - means the key value pointer should be NULL.
X means the key value specified will be included.
O means the key value specified will be excluded.
KeyFrom should be BEFORE or AFTER KeyTo, depending on whether
the key is an ascending or descending key.
If KeyFrom and KeyTo are in the wrong order,
ERROR_KEY_IS_ASCENDING or ERROR_KEY_IS_DESCENDING will be
returned.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the iteration
IterType - the type of iteration range (currently, 0-9)
KeyFrom - a pointer to the key value from which to range, or NULL
KeyTo - a pointer to the key value to which to range, or NULL
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
ISAM.doc (for a complete discusson on itertypes and ranges)
===============================================================================
isam.library/SetUpISAMIterationKey isam.library/SetUpISAMIterationKey
NAME
SetUpISAMIterationKey -- set up an iteration on one key value.
SYNOPSIS
error = SetUpISAMIterationKey ( ISAMHandle, KeyNo, KeyValue )
long SetUpISAMIterationKey ( ULONG, UWORD, void * );
FUNCTION
This function sets up an iteration on one key value for key KeyNo,
for the specified ISAM File.
NOTES
Subsequent ReadNextISAM(Key|Record) calls will result in records
being found with key values matching KeyValue.
This is equivilent to calling SetUpISAMIterationRange with IterType
being set to 1.
If the given key is unique, using the single function ReadUniqueISAM-
Record will achieve the same result with less code.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
KeyNo - the key number of the iteration
KeyValue - a pointer to the key value being sought
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
ISAM.doc
===============================================================================
isam.library/SetUpISAMIterationPrefix isam.library/SetUpISAMIterationPrefix
NAME
SetUpISAMIterationPrefix -- set up an iteration on a key value prefix
SYNOPSIS
error = SetUpISAMIterationPrefix ( ISAMHandle, KeyNo, Prefix, Len )
long SetUpISAMIterationPrefix ( ULONG, UWORD, void *, UWORD );
FUNCTION
This function sets up an iteration on a key value prefix, for key
KeyNo, for the specified ISAM File.
NOTES
Subsequent ReadNextISAM(Key|Record) calls will result in records
being found with all key values having the given prefix.
This function is only valid for keys of type A, T, and UI, as a
"prefix" on a floating-point or signed-integer key is meaningless,
and type C is of length 1 and hence can't HAVE a prefix. Code
ERROR_INVALID_TYPE will be returned if the wrong type is used.
Len is used with non-text keys, whose length cannot be determined
by strlen(), and for those situations when the prefix is stored in
the middle of something else (and hence has no \0). If the prefix
IS a string, Len may be set to zero, and strlen() will be used to
set the true length.
If the length of the prefix is equal to the length of the key, then
this function is the equivilent of SetUpISAMIterationKey.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
KeyNo - the key number of the iteration
Prefix - a pointer to the prefix
Len - the length of the prefix, or zero
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
ReadNextISAM(Key|Record), CountISAMRecords, DeleteISAMRecords,
ISAM.doc
===============================================================================
isam.library/ShutDownISAM isam.library/ShutDownISAM
NAME
ShutDownISAM -- shuts down the ISAM server
SYNOPSIS
error = ShutDownISAM ( )
long ShutDownISAM ( void );
FUNCTION
This function shuts down the ISAM server.
NOTES
The code ERROR_ISAM_SHUTTING_DOWN will be returned by this function,
and by all other functions already waiting to be processed.
Shutting down ISAM will annoy other users, so this should be avoided.
This function unlocks all locked records and [unlocks]/closes
all open files for all users before the server goes away.
INPUTS
none
RESULTS
error - returns ERROR_ISAM_SHUTTING_DOWN.
BUGS
SEE ALSO
===============================================================================
isam.library/StoreISAMRecord isam.library/StoreISAMRecord
NAME
StoreISAMRecord -- store a record
SYNOPSIS
error = StoreISAMRecord ( ISAMHandle, Record, LLock, LockType, RecNo )
long StoreISAMRecord ( ULONG, void *, BOOL, char, ULONG * );
FUNCTION
This function stores a record in the specified ISAM file.
If LLock is TRUE, an attempt will be made to lock the record with
lock type LockType.
NOTES
If the file contains a unique key, and the record being stored
has a key value for that key that already exists in the file,
the code ERROR_RECORD_EXISTS will be returned.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file
Record - a pointer to the area of memory in which the record is
stored
Normally this will be the address of a struct
(example: "&AddrRec" ).
LLock - TRUE / FALSE
LockType - 'W' (exclusive) or 'R' (shared)
RecNo - a pointer to the variable into which the record number of
the record being stored will be placed (example: &RecNo )
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
===============================================================================
isam.library/UnLockISAMFile isam.library/UnLockISAMFile
NAME
UnLockISAMFile -- unlock an ISAM file
SYNOPSIS
error = UnLockISAMFile ( ISAMHandle )
long UnLockISAMFile ( ULONG );
FUNCTION
The specified ISAM file is unlocked.
If the value ALLFILES is given for ISAMHandle, then all of the files
that the user has locked will be unlocked.
NOTES
No error is returned if the file wasn't locked.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file, or
ALLFILES
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
LockISAMFile
===============================================================================
isam.library/UnLockISAMRecord isam.library/UnLockISAMRecord
NAME
UnLockISAMRecord -- unlock a record
SYNOPSIS
error = UnLockISAMRecord ( ISAMHandle, RecNo )
long UnLockISAMRecord ( ULONG, ULONG );
FUNCTION
This function unlocks the specified record in the specified ISAM file.
NOTES
No error is returned if the file wasn't locked.
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
RecNo - the record number of the record being unlocked.
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
LockISAMRecord, UnLockAllISAMRecords
===============================================================================
isam.library/UnLockAllISAMRecords isam.library/UnLockAllISAMRecords
NAME
UnLockAllISAMRecords -- unlock all locked records
SYNOPSIS
error = UnLockAllISAMRecords ( ISAMHandle )
long UnLockAllISAMRecords ( ULONG );
FUNCTION
This function unlocks all locked records in the specified ISAM file.
If the value ALLFILES is given for ISAMHandle, then all of the locked
records for all of the files that the user has open will be unlocked.
NOTES
INPUTS
ISAMHandle - the ISAM Handle identifying the desired ISAM file.
RESULTS
error - returns OK, or an errorcode.
BUGS
SEE ALSO
UnLockISAMRecord
===============================================================================