jan, 2009 - offical release of DISAM v7.0 new to this release
----------------------------------------------------------------------------
isopen.c, isbuild.c, isvarlen.c, isvarlen.h and isconfig.h - changes to
variable length idx file format to allow for > 16777216 record limit when
storing record numbers in 3 char bytes for varinfo and continuation node
pointers. isconfig.h setting ISOLDVARLEN 1 or any non 0 ISCISAM setting
will maintain old disam/c-isam variable length file format compatibility.
ISCISAM 0 and ISOLDVARLEN 0 ensures new format. new format requires that
dvlrebld( see dvlrebld.ref ) be run on existing variable length files.

stdextra.c - schema/record layout support - new wrap functions
load schema from isamfile to path/filename
ISD1 int ISD2 isldschema( int isfd, char *path )
dump schema from isamfile to stdout
ISD1 int ISD2 isdpschema( int isfd )
store schema from loadfile to isamfile
ISD1 int ISD2 isstschema( int isfd, char *loadfile )
remove schema from isamfile
ISD1 int ISD2 isrmschema( int isfd )

isschema.c - schema record layout support - new base functions
load schema from isamfile to path/filename
ISD1 int ISD2 isLdSchema( IsFile *isam, char *path )
dump schema from isamfile to stdout
ISD1 int ISD2 isDpSchema( isFile *isam )
store schema from loadfile to isamfile
ISD1 int ISD2 isStSchema( IsFile *isam, char *loadfile )
remove schema from isamfile
ISD1 int ISD2 isRmSchema( IsFile *isam )
* see read/schema.ref for function details and schema/ReadMe for sample programs

dreport.c - new schema related isam data reporting utility.

record number limit changed from LONG_MAX to ULONG_MAX value

client/server capabilities incorporated into standard DISAM. for a free limited single client server program please contact ByteDesigns.
-----------------------------------------------------------------------------

Back to top

upgrading from old disam
---------------------------------------------------------------------

the process of upgrading from older versions of disam should be as
simple as relinking with the new library, but there are a few things
that are different, and may need addressing.


---------------------------------------------------------------------
the header file
---------------------------------------------------------------------

the standard header file as distributed is named iswrap.h to avoid
confusion with older versions and to differentiate from the alternate
interface header, which is called isbase.h

the simplest procedure is to replace the contents of your original
disam.h with a copy of iswrap.h

alternatively you might wish to create a new copy of disam.h which
does nothing more than include either iswrap.h or a renamed copy of
your old disam (or cisam) header file. this would permit you to
easily switch back and forth until you are comfortable with the new
library.


---------------------------------------------------------------------
the trouble with isfdmap
---------------------------------------------------------------------

the old disam library used an array of pointers, called isfdmap, to
manage it's table of open files. the new library uses an internally
manipulated dynamic array that is not quite as easy to get to, and
the associated file descriptor structure has changed significantly.

analogs for the more common values are now available via the
common dictionary access routines described in wrap.ref

please let support know if anything important has been left out.


---------------------------------------------------------------------
virtual file open handling (ISVIRTUAL define in old isport.h)
---------------------------------------------------------------------

older versions of disam included a compile time option for
virtual file handling support. this was activated by means
of the ISVIRTUAL define in isport.h

it was designed to allow the library to bypass the system
file handle limit by swapping out (closing) inactive system
handles to make room for new opens.

because it is not possible to retain locks on closed system
handles, this feature introduced a bug that created problems
with index access concurrency, sometimes resulting in index
corruption.

at time of writing there appears to be no practical solution
to this problem, and virtual file handling support has been
discontinued in the current release.

the current library provides an alternative solution (although
not as extensive) via duplicate open handling. this feature,
active by default, allows the library to multiplex the system
handles used to access multiple opens on the same isam file.

in other words - you can open the same isam file as often as
you wish without the need for additional system handles.

while this does not cover instances where the application
needs to access large numbers of different isam files, it
should be of value under the circumstances denoted.

no specific configuration is needed to access this feature,
as it is an integral part of standard operation.


---------------------------------------------------------------------
isindex( int isfd, int idx, int locate );
---------------------------------------------------------------------

the idx argument has been changed. under old disam, a value of zero
was used to select the primary index, and a value equal to the max
number of active indexes was used to select natural order.

the new library uses a value of zero to denote natural order, and
the active index count starts at one.

if you prefer the original functionality, please refer to the pre-
processor directive within the islocate code in stdread.c


---------------------------------------------------------------------
ispop( int isfd, int idx, long rec );
---------------------------------------------------------------------

the idx argument has been changed. under old disam, a value of zero
was used to select the primary index, and a value equal to the max
number of active indexes was used to select natural order.

the new library uses a value of zero to denote natural order, and
the active index count starts at one.

if you prefer the original functionality, please refer to the pre-
processor directive within the ispop code in stdread.c

if you change ispop functionality you should make the same change
in ispush.


---------------------------------------------------------------------
ispush( int isfd, int *idx, long *rec );
---------------------------------------------------------------------

since the new library no longer supports the isfdmap array, this call
has been added to load the current index and record numbers for later
use by ispop.


---------------------------------------------------------------------
isclone( int isfd, char *name );
---------------------------------------------------------------------

you can no longer specify the mode of the new file, nor list the
indexes to be copied. if this is a problem to you please let the
support department know - the option was dropped because it was felt
that it had limited use and the associated varargs processing caused
an amount of difficulty in porting.

the current version copies all indexes by default, and the open mode
of the returned handle will be the same as for the original file.


---------------------------------------------------------------------
iscopy( int isfd, char *name );
---------------------------------------------------------------------

iscopy no longer requires that you pass a buffer to assist in the
copying process, and the extraneous flags argument has been dropped
because it was never used.


---------------------------------------------------------------------
isgetmode( int isfd, int *mode );
---------------------------------------------------------------------

this routine loads the open mode value into the mode pointer passed


---------------------------------------------------------------------
ISAUTOLOCK behaviour
---------------------------------------------------------------------
Disam by default release automatic record locks only on a subsequent
read. For older D-ISAM v3.x behaviour set isconfig.h D3XAUTOLOCK
to 1 to enable automatic release on read, update or delete

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

base library reference
---------------------------------------------------------------------

the library provides two separate interface methods. the base code
uses allocated file descriptors ( similar to fopen/fwrite etc ) to
manage isam files, and it will be this interface that is described
here. the differences between the base and the wrapper interfaces
is covered in wrap.ref


---------------------------------------------------------------------
primary details
---------------------------------------------------------------------

all modules which make base library calls should include isbase.h

in all of the following, isfd will be used to refer to an open isam
file descriptor, as returned by isOpen or isBuild, and declared as:

struct IsamFile *isfd; /* the formal way */
IsFile *isfd; /* typedef shortcut */


---------------------------------------------------------------------
return values and result indicators
---------------------------------------------------------------------

with the exception of isBuild, isOpen and a few others, the base will
return a boolean ISTRUE or ISFALSE. ISTRUE and ISFALSE are defined
in the isbase.h header as 1 and 0 respectively.

when ISFALSE is returned you will find the system or isam error code
in isfd->iserrno, where isfd is an open file descriptor. isam error
codes start at 100 (refer to ISERRBASE in install.ref if you need to
change this) and are listed under error codes below. system error
codes have their usual values for the target system.

if iserrno is less than 100 (ie a system error) isfd->iserrio will
provide a little more detail as to where and why, as listed under
errio codes below.

in situations where no file descriptor is available, such as when
isBuild or isOpen fail, or after isClose, isErase or isRename, the
call will return the error code in the global errno variable.


---------------------------------------------------------------------
IsFile *isBuild( char *name, int dlen, int mlen, IsKdsc *key, int mode );
---------------------------------------------------------------------
name: [path]name of file to be created
dlen: length of data record in bytes
mlen: if ISVARLEN then max record length else ignored
key: primary index description, see isam indexes
mode: see open modes
return: allocated file descriptor or NULL

note: if successful, isBuild will return an isam file descriptor
open in the specified mode and ready for use.

a NULL pointer is returned on failure and the error code will
be found in the global errno variable.

refer to varlen.ref for more details regarding ISVARLEN

---------------------------------------------------------------------
IsFile *isOpen( char *name, int mode );
---------------------------------------------------------------------

name: [path]name of an existing isam file
mode: see open modes
return: allocated file descriptor or NULL

note: the file name must be specified without the .dat or .idx
extension, and must be less than 251 bytes in length.

the current index will be set to the primary.

a NULL pointer is returned on failure and the error code will
be found in the global errno variable.


---------------------------------------------------------------------
int isCleanUp( void )
---------------------------------------------------------------------

note: this routine will close all currently open isam files and
release all allocated global memory.

only available if the base library was compiled with the
ISADMIN feature activated.


---------------------------------------------------------------------
IsFile *isLockCheck( IsFile *isfd, int mode );
---------------------------------------------------------------------

isfd: isam file descriptor
flag: 0: off 1:on

note: a flag value of 1 will cause the library to fail on
update or delete if the record in question has not
been successfully locked prior to the operation. the
iserrno value returned in this instance is ENOCURR.


---------------------------------------------------------------------
IsFile *isSetMode( IsFile *isfd, int mode );
---------------------------------------------------------------------

isfd: isam file descriptor
mode: either ISMANULOCK or ISAUTOLOCK

note: this routine can be used to switch the designated file between manual and automatic locking modes.

when switching from automatic to manual, the current record,
if locked, will be released.

future plans include the ability to switch to/from exclusive
lock as well, but at present an attempt to do so will result
in an EBADARG error.


---------------------------------------------------------------------
IsFile *isClose( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: isClose drops all locks and releases all allocated memory.

isClose will return FALSE on failure and the error code will
be found in the global errno variable.


---------------------------------------------------------------------
int isAddIndex( IsFile *isfd, IsKdsc *key );
---------------------------------------------------------------------

isfd: isam file descriptor
key: description of secondary index to add, see isam indexes

note: when adding an index to a populated file, isAddIndex will
load the new index with keys for all the existing data
records. in the case of larger files this could take a
while..

isAddIndex will attempt to place an exclusive lock on
the isam file for the duration of the update (assuming
you have not done so already) and will fail if any other
process already has the file open.


---------------------------------------------------------------------
int isDelIndex( IsFile *isfd, IsKdsc *key );
---------------------------------------------------------------------

isfd: isam file descriptor
key: description of secondary index to delete, see isam indexes

note: when deleting an index from a populated file, isDelIndex will
purge the accumulated keys. in the case of larger files this
could take a while, but will be significantly faster than the
isAddIndex call.

isDelIndex will attempt to place an exclusive lock on
the isam file for the duration of the update (assuming
you have not done so already) and will fail if any other
process already has the file open.


---------------------------------------------------------------------
IsFile *isCluster( IsFile *isfd, IsKdsc *key );
---------------------------------------------------------------------

isfd: isam file descriptor
key: description of index to cluster on

note: the file must be open in exclusive mode

this routine makes use of a temporary file, created in the
same directory as the original.

all active data records will be transferred to the temp file
in the index order specified, and all indexes will be packed
as efficiently as possible.

if successful, isCluster will return a new file descriptor,
opened in the same format as the original, which will be
abandoned. a NULL pointer will be returned on error, and
the original descriptor and file will be left intact.

be warned that this call may take some time to run if the
file in question is large.


---------------------------------------------------------------------
int isErase( char *name );
---------------------------------------------------------------------

name: [path]name of an existing isam file to be physically removed.

note: isErase will not remove files that are currently in use by
other processes.

the error code will be found in errno on failure.


---------------------------------------------------------------------
int isRename( char *old, char *new );
---------------------------------------------------------------------

old: original [path]name of an existing isam file
new: new [path]name of isam file

note: isRename will not rename files that are currently in use by other processes.

isRename can be used to move an isam file from one directory
to another, but not to a different drive or device.

the error code will be found in errno on failure.


---------------------------------------------------------------------
int isStart( IsFile *isfd, IsKdsc *kdsc, int len, char *data, int mode );
---------------------------------------------------------------------

isfd: isam file descriptor
kdsc: description of index to be selected or NULL to retain the current index
len: partial length of key, or 0 for full
data: data record pointer if needed for search mode, or NULL
mode: see search modes

note: this routine has multiple purposes.

if kdsc is passed then the index described will become current.

if length is non zero then isStart will set a partial key
length for the selected index, and will only consider the
first len bytes of the key during subsequent searches. this
will remain in effect until the next isStart call.

the selected location in the index will be flagged as a start
point, which means that the next call to isRead, if made with
a search mode of ISNEXT or ISPREV, will return the current
record, rather than the actual next or previous. this is often
useful for initialising next or previous read loops.

after a successful isStart call, isfd->isrecnum will be set to
the current record number.


---------------------------------------------------------------------
int isRead( IsFile *isfd, char *data, int mode );
---------------------------------------------------------------------

isfd: isam file descriptor
data: pointer to data buffer to be loaded
mode: search mode plus optional lock mode

note: if successful isfd->isrecnum will be set to the current record
number.

when isRead is called with ISLOCK, and the record requested
is currently locked by another process, isRead will return
ISFALSE with an iserrno value of ELOCKED but will still have
read the requested record into the data buffer.


---------------------------------------------------------------------
int isIndex( IsFile *isfd, int index );
---------------------------------------------------------------------

isfd: isam file descriptor
index: index number to select

note: isIndex is used to select indexes by number. if index is
zero then natural order will be selected, otherwise indexes
are numbered starting at one for the primary index.

isIndex retains a current record pointer for each index.
after selection the current pointer will be at the record
selected when the index was last used.


---------------------------------------------------------------------
int isGoto( IsFile *isfd, long recnum );
---------------------------------------------------------------------

isfd: isam file descriptor
recnum: an existing active record number

note: this call will locate the specified record in the current
index, making it the current index location.

if successful, the specified record image will be found in
isam->data.


---------------------------------------------------------------------
int isData( IsFile *isfd, char *data, long recnum );
---------------------------------------------------------------------

isfd: isam file descriptor
data: pointer to data buffer to be loaded
recnum: an existing active record number

note: isData performs a direct read on the data file, and does not
disturb the current index pointer, and does not check for
record locks. it will return ENOREC if the record requested
does not exist or has been deleted.

isData is provided primarily as a means of accessing data
records in as an efficient a manner as possible.


---------------------------------------------------------------------
int isWrite( IsFile *isfd, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
data: pointer to data record to be written

note: if successful this call will add the data record to the data
file and create an appropriate key in all indexes.


---------------------------------------------------------------------
int isWrLock( IsFile *isfd, char *data );
---------------------------------------------------------------------

note: as for isWrite, but the resultant data record will be locked
on successful return.


---------------------------------------------------------------------
int isWrCurr( IsFile *isfd, char *data );
---------------------------------------------------------------------

note: as for isWrite, but the current pointer in the current index
will be set to the record just written.


---------------------------------------------------------------------
int isDelete( IsFile *isfd, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
data: data record to be deleted

note: the record image passed is expected to contain enough data
to cover the fields required by the primary index.

if the primary index allows duplicates this call will fail,
since isDelete has no means of determining exactly which
record you are referring to.

the original data image can be found in isfd->data on return.


---------------------------------------------------------------------
int isDelCurr( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: this call will delete the currently selected record.

the original data image can be found in isfd->data on return.


---------------------------------------------------------------------
int isDelRec( IsFile *isfd, long recnum );
---------------------------------------------------------------------

isfd: isam file descriptor
recnum: record number to be deleted

note: the original data image can be found in isfd->data on return.


---------------------------------------------------------------------
int isRewrite( IsFile *isfd, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
data: data image to be updated

note: the record to be updated is determined by the contents of
the primary index fields as found in the data image passed.

if the primary index allows duplicates this call will fail.

the original data image can be found in isfd->data on return.


---------------------------------------------------------------------
int isRewCurr( IsFile *isfd, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
data: data record to be updated - the contents of the current record in the data file will be replaced with the image passed.

note: the original data image can be found in isfd->data on return


---------------------------------------------------------------------
int isRewRec( IsFile *isfd, long recnum, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
recnum: record number to be replaced
data: data image with which recnum is to be replaced.

note: the original data image can be found in isfd->data on return


---------------------------------------------------------------------
int isRewNxt( IsFile *isfd, char *data );
---------------------------------------------------------------------

isfd: isam file descriptor
data: data record to be updated - the contents of the current record in the data file will be replaced with the image passed.

note: isRewNxt first sets the current pointer to the next record in
the current index before updating the original current record.

it is useful in situations where the update would place the
new record between the original current and next keys in the
index.

on successful return the application can then read current to
obtain the record that was next in the sequence before the
update was performed.

an error code of EENDFILE on an unsuccessful return indicates
that the update was successful and isRewNxt has reached the
end of the file. any other error code indicates a failure
in the update operation.

the original data image can be found in isfd->data on return


---------------------------------------------------------------------
int isLock( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: this call will lock all records in the file against update
by any process other than the current, or return ELOCKED if
this is not possible.


---------------------------------------------------------------------
int isUnLock( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: reverses the action of isLock


---------------------------------------------------------------------
int isRelease( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: this call will release any records that have been manually
or automatically locked by the current process.


---------------------------------------------------------------------
int isRelRec( IsFile *isfd, long recnum );
---------------------------------------------------------------------

isfd: isam file descriptor
recnum: record number to be unlocked


---------------------------------------------------------------------
int isRelCurr( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: unlock the currently selected record


---------------------------------------------------------------------
int isSetUnique( IsFile *isfd, long value );
---------------------------------------------------------------------

isfd: isam file descriptor
value: new unique value starting point

note: this will set the value returned by the next call to isUniqueID.


---------------------------------------------------------------------
int isUniqueId( IsFile *isfd, long *value );
---------------------------------------------------------------------

isfd: isam file descriptor
value: pointer to variable to receive value

note: the value returned is guaranteed unique for the current file.


---------------------------------------------------------------------
int isIndexInfo( IsFile *isfd, IsKdsc *kdsc, int idx );
---------------------------------------------------------------------

isfd: isam file descriptor
kdsc: pointer to dictinfo or key description structure
idx: zero for dictinfo, otherwise index number

note: this call serves two somewhat different purposes.

if idx is zero, then it's actually expecting you to pass
a pointer to a dictinfo structure, which will then be
loaded with information about the current file. refer to
isIsamInfo below for a somewhat cleaner method.

if idx is non zero then isIndexInfo will return the specified
key description, where a value of 1 represents the primary,
followed by each successive index in the file.


---------------------------------------------------------------------
int isIsamInfo( IsFile *isfd, struct dictinfo *dict );
---------------------------------------------------------------------

isfd: isam file descriptor
dict: pointer to dictinfo structure

note: this call will return information about the specified file
in the structure passed. the values available are:

short di_nkeys; /* number of indexes */
short di_recsize; /* data record length */
short di_idxsize; /* index record block size */
long di_nrecords; /* current record count */


---------------------------------------------------------------------
int isCheckData( IsFile *isfd );
---------------------------------------------------------------------

isfd: isam file descriptor

note: this routine checks the data file and data file free list for
errors, and will return a value with the following bits set
in accordance with it's findings:

IC_DATREAD 0 /* data file read error */
IC_BADDATA 1 /* data record corrupt */
IC_DATFREE 2 /* data free list is corrupt */

if the return value is zero then no errors were detected.


---------------------------------------------------------------------
int isCheckIndex( IsFile *isfd, int idx );
---------------------------------------------------------------------

isfd: isam file descriptor
int: key id number, where 1 represents the primary

note: this routine checks the specified index for errors, and will
return a value with the following bits set in accordance with
it's findings:

IC_IDXREAD 3 /* index file read error */
IC_ORDER 4 /* key out of order */
IC_COUNT 5 /* index count mismatch */
IC_BADMAGIC 6 /* bad index node magic number */

if the return value is zero then no errors were detected.


---------------------------------------------------------------------
int isCheckVarlen( IsFile *isam, struct isVarStat *stats );
---------------------------------------------------------------------

isfd: isam file descriptor
stats: variable length statistics structure, defined in ischeck.h, or NULL to ignore same.

note: this routine checks the variable length storage system for
errors, and will return a value with the following bits set
in accordance with it's findings:

IC_VLMISFILE 12 /* node misfiled in hash table */
IC_VLHASHLINK 13 /* mangled link in hash list */
IC_VLMISSING 14 /* nodes missing or unaccounted */
IC_VLBADDATA 15 /* data length mismatch */

it will also optionally load the following fields in stats:

hashcount; /* number of nodes held in hashtable */
hashspace; /* total bytes free space in same */
fullcount; /* number of nodes not in hashtable */
fullspace; /* total (unusable) space in same */
filecount; /* total number of storage nodes in use */
filespace; /* total free space for the file */


---------------------------------------------------------------------
machine independent data
---------------------------------------------------------------------

the library includes the following series of calls to provide a means
of generating data that will be transportable to different machines.
use of these is only required if you require such portability, since
the library will accept native formats without complaint.

int ldInt( char *pad );
int stInt( int value, char *pad );
long ldLong( char *pad );
int stLong( long value, char *pad );
int stChar( char *pad, char *str, int len );
int ldChar( char *pad, int len, char *str );
double ldFloat( char *pad );
int stFloat( double value, char *pad );
double ldDbl( char *pad );
int stDbl( double value, char *pad );
int stFltNull( double value, char *pad, short *null );
double ldFltNull( char *pad, short *null );
int stDblNull( double value, char *pad, short *null );
double ldDblNull( char *pad, short *null );

in all of the above, st identifies calls that will place a value in
the specified location, which can then be retrieved by the matching
ld call. the null suffix calls will load the variable passed (by
address) in the last parameter with a boolean ISTRUE if the associated
value is zero, or ISFALSE if not.

all pads referred to should be the size of the associated data type,
with the exception of ldInt/stInt, which refer to a two byte integer,
regardless of the native word size.

note that the float and double calls do not perform any actual data
conversion, and are provided as a means of avoiding data alignment
problems. the int and long calls will perform byte order reversal
(sometimes referred to as swabbing) on platforms where the least
significant byte is found at the beginning of the field.

note also that ldint and stint operate on short (2 byte) integers,
although the value and return are passed in the natural word size.


---------------------------------------------------------------------
isam indexes
---------------------------------------------------------------------

isam indexes are defined/described by means of the keydesc structure.

the following is an example of the basic procedure, and describes an
index that allows duplicates, has full compression, and consists of
two fields - a machine independent integer taken from the first two
bytes of the record, and a character string from the seventh through
sixteenth bytes.

struct keydesc key;

key.k_flags = ISDUPS+ISCOMPRESS; /* see index flags */
key.k_nparts = 2; /* number of fields involved */
key.k_part[0].kp_start = 0; /* offset in data record */
key.k_part[0].kp_leng = INTSIZE; /* length */
key.k_part[0].kp_type = INTTYPE; /* type */
key.k_part[1].kp_start = 7; /* offset in data record */
key.k_part[1].kp_leng = 10 * CHARSIZE; /* length */
key.k_part[1].kp_type = CHARTYPE; /* type */

this structure is then passed to isBuild, isAddIndex, or isStart.


index flag values - these apply to the index as a whole

ISNODUPS no duplicates permitted
ISDUPS duplicates permitted
DCOMPRESS compress duplicates
LCOMPRESS leading compression
TCOMPRESS trailing space compression
COMPRESS full compression
TNULL compress on nulls in TCOMPRESS


individual index component/part/field types

CHARTYPE 0 array of bytes/characters
INTTYPE 1 two byte (short) integer
LONGTYPE 2 four byte (long) integer
DOUBLETYPE 3 ieee double floating point
FLOATTYPE 4 ieee single floating point
MINTTYPE 5 machine (native) short
MLONGTYPE 6 machine (native) long

ISDESC 0x80 add to individual parts for descending order


it is generally advisable to provide some callable means of loading
your key descriptions into a keydesc structure, or to provide some
other means of easy access, since they will be needed for selecting
indexes via isStart.

you will also need to exercise caution when using CHARTYPE fields
as the library does not recognise null terminated strings. in other
words, if you're referring to a 10 byte wide character field, and it
contains a seven byte string, a null terminator and 2 garbage bytes
following the null, the library will build a key 10 bytes in length
that includes the null and trailing garbage. this key might prove
difficult to locate later..

the officially approved solution is to use the included stchar() and
ldchar() calls, which will pad the string passed with spaces on store
and replace the null terminator on load.

note also that trailing compression operates on strings of trailing
spaces, so the fairly common practice of padding the remainder of
the field with nulls could result in inefficient operation where
trailing compression is expected.


---------------------------------------------------------------------
open modes
---------------------------------------------------------------------

there are two different groups of open modes used by the isOpen and
isBuild calls. the first group describes the operations which the
current process will be allowed to perform, while the latter controls
what forms of external access will be permitted. you must chose one
from each list.

ISINPUT open file for reading only
ISOUTPUT open file for writing only
ISINOUT open file for both reading and writing
ISSYNCWR all writes flushed to disk before return

ISMANULOCK record locks placed manually
ISAUTOLOCK record locks placed automatically on read
ISEXCLLOCK exclusive access to index and data
ISRDONLY read only - no locking

ISVARLEN variable length records - see varlen.ref
ISVARCMP RLE compressed varlen data
ISNOCARE open either fixed or variable length

ISMASKED index masking option - see mask.ref

ISTRANS transaction processing - see trans.ref
ISNOLOG disable logging - see trans.ref


NOTE: ISSYNCWR is only active for systems that permit O_SYNC in the
file open call. this precludes most DOS flavoured systems.


---------------------------------------------------------------------
search modes
---------------------------------------------------------------------

all isRead operations act on the currently selected index.

ISFIRST select the first record in the index
ISLAST select the last record in the index

ISEQUAL search for and return the first exact match, or error
ISGTEQ search for first exact match, or next greater
ISGREAT search for the next greatest key in the index

ISNEXT skip to the next key in the index
ISPREV skip to the previous key in the index
ISCURR reread the current location.

note ISNEXT and ISPREV behave differently when used in isRead
immediately after in isStart call in that they will return
the current rather than the next/previous record.

this is a feature, not a bug. the intention is to allow
isStart to function as an initialisation call preceding
a read next/previous loop, as in the following:

isStart( isfd, &secondary_index, 0, NULL, ISFIRST );
while( isRead( isfd, data_pointer, ISNEXT ) )
display_data( data_pointer );

the above will read the contents of isfd from the top in
secondary_index order.


---------------------------------------------------------------------
lock modes
---------------------------------------------------------------------

these are added to the search mode in isRead to lock or wait for the
release of the selected record.

ISLOCK lock the selected record against external update
ISWAIT wait until the selected record has been released
ISLCKW wait for and unlock the selected record

ISLOCK will return an ELOCKED error if the selected record has been
locked, but will still return the selected record image. this allows
the process to read an externally locked record, but warns that updates
will not be permitted.

ISWAIT and ISLCKW do no deadlock processing, and will wait forever, so
applications should be coded appropriately.

the isLock, isUnLock, isRelease, isRelRec and isRelCurr group of
functions provide further control over record locking, and you can
also use ISEXCLLOCK to lock other processes out of a file completely.


---------------------------------------------------------------------
error codes
---------------------------------------------------------------------

in addition to the standard operating system error codes, the library
will return the following values in isfd->iserrno where appropriate.

EDUPL 100 illegal duplicate
ENOTOPEN 101 file not open
EBADARG 102 illegal argument
EBADKEY 103 illegal key description
EBADFILE 105 isam file is corrupt
ENOTEXCL 106 can't get exclusive access
ELOCKED 107 record is locked
EKEXISTS 108 index already defined
EENDFILE 110 start or end file reached
ENOREC 111 record not found
ENOCURR 112 no current record
EFLOCKED 113 file is locked
EFNAME 114 file name is too long
EBADMEM 116 can't allocate memory
ENOPRIM 127 no primary key

when the library returns a system error code it will also load
isfd->iserrio with the sum of the following two groups of values:

IO_IDX 0x01 index file
IO_DAT 0x02 data file

IO_OPEN 0x10 while opening
IO_CREA 0x20 while creating
IO_SEEK 0x30 while seeking
IO_READ 0x40 while reading
IO_WRIT 0x50 while writing
IO_LOCK 0x60 while locking


---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

suggestions, pitfalls and defenses
---------------------------------------------------------------------

long duplicate chains
---------------------------------------------------------------------

if you are using keys that will result in a large number of duplicate
records, you should be warned that deletes and rewrites within these
can become painfully slow. this is due to the fact that, when you
request an update or delete, the library is forced to start at the
beginning of the chain and read sequentially through each looking
for the record number you are referring to.

the isam standard does not currently appear to offer a solution to
this problem, but if anyone has any suggestions you can be sure we'll
be interested.

if this is a concern, specifically during long update runs that will
be doing a large amount of duplicate key changes, you might wish to
consider deleting the offending indexes before you start, and adding
them again after the run is complete. this is potentially dangerous,
of course, but the advantages will be significantly faster processing
times and better balanced trees on completion.

long duplicate chains are not a problem when writing or reading, since
writes get tacked onto the end of the chain, and reads are sequential
by definition.


duplicate open files
---------------------------------------------------------------------

isam allows you to open the same file many times within a given
process. cisam and older disam also allowed some rather dangerous
operations on these files. for instance:

fd = build file
erase file
write records to fd
close file

none of the above will return any errors, but you won't be able
to open the file again because it has been erased from the file
system - everything written has been discarded.

the ISDUPLOCKS option in isconfig.h, when set to a value of one,
will prevent the library from erasing or renaming files which are
already open in the current process.

when ISDUPLOCKS is zero this will not be enforced, and it is up to
the application to apply the appropriate degree of caution.


---------------------------------------------------------------------
COMPRESS/LCOMPRESS/TCOMPRESS

ISKCOMP 0
due to fixed index file format specifications, a single char is used
to store the number of leading compressed bytes and another to store
the number of trailing compressed bytes. this forces a limitation
of 255 bytes ( max unsigned char ) for compressed key size,
regardless of ISMAXKEY setting to ensure full compression of all
trailing spaces or nulls for TCOMPRESS, and all leading duplicate
characters for LCOMPRESS.

ISKCOMP 1
allows compressed key sizes larger than 255 bytes, but will only
permit partial compression on leading and trailing characters.
a maximum of 255 leading duplicate characters, and 255 trailing
spaces or nulls will be compressed.



---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

large files - 64bit implementation
---------------------------------------------------------------------------

as of version 6.12 we have attempted to implement 64bit support for
large files. todate most unix platforms as well as NT are supported.
as more systems develop 64bit capability we will add the same support for
disam. we have attempted to make switching to 64bit support as
simple as setting a compile time flag..ISHUGE found in isconfig.h. you
may need to redefine the ISHUGE related settings for OFFT and UOFFT,
depending on how your OS handles large file support and lseek offsets.
second level support can be found in isbase.h where platform specific
functions such as lseek64 are defined.

please let us know if you require 64bit functionality for your platform,
or if you successfully manage to get 64bit working on any platform not
currently setup.

---------------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------------

Back to top

design concepts
----------------------------------------------------------------------

in order to facilitate thread safe programming, the core library has
been developed to use isam file descriptor structures, rather than
the standard integral handle concept. the external function calls
are named after the original function names, but use capital letters
to keep them separate, as in isOpen rather than isopen. the status
and information globals, such is iserrno and iserrio, have been
eliminated, and each file descriptor now carries it's own copy.

the standard (lower case) calls are provided as an optional wrapper
layer which maintains a dictionary of descriptors to allow mapping
via the standard integer file handles. it also defines and passes
the standard global variables.

----------------------------------------------------------------------
conventions
----------------------------------------------------------------------

all public library function names start with 'is' and use capital
letters to distinguish keywords.

all structure definitions and typedefs start with a capital letter,
and use the same capitalisation rules to distinguish keywords.

the posix standard system calls are wrapped in functions prefixed
by is and an underscore.

local support routines in each module are named in lowercase.

macro definitions are all capitals.

virtually all entry and internal functions return TRUE on success
and FALSE on failure. TRUE is defined as 1, FALSE is 0.


----------------------------------------------------------------------
buffering
----------------------------------------------------------------------

the tree node buffering system operates by handing node images which
are no longer part of the current path to a storage mechanism. each
index carries it's own path list and storage array.

a single linked list holds the current path and facilitates traversal
without having to move data around. the node description structures,
which contain current status information and a copy of the node disk
image, are are passed to and from the path list and the buffer array
as pointers.

the buffer cache is currently optimised on a last in first out basis.
it might be worthwhile to consider optimising this further by giving
a degree of precedence to nodes from lower levels in the tree, on the
assumption that these will take more hits.

buffers are flagged invalid whenever the index file header transaction
count has been changed by another process, and will be refreshed as
required.

at some point in the future, at the cost of cisam concurrency, it may
be worthwhile to consider designing a more detailed currency control
which would maintain separate transaction counts for each index, and
perhaps additional counts for the index and data free lists, variable
length storage space, and so on.

the same buffering system provides a failsafe error recovery method
in which updated node images are flagged invalid on error, which then
results in a forced refresh before the image can be used again. this
method allows for optimistic updates, eliminating the need to check
first before embarking on potentially illegal updates. see error
handling below for more details.


----------------------------------------------------------------------
uncompressed (flat) versus compressed indexes
----------------------------------------------------------------------

for the dual purpose of keeping the code cleaner and to improve
performance, the index handling routines are split into separate
functions where the associated handling is markedly different.

flat indexes, in general, can be operated on mathematically, lend
themselves to shell searches, and permit the current key value to
be a simple pointer into the node image.

compressed indexes require that each node be searched in a linear
fashion, building the key image in an allocated buffer en route,
and generally require a fair amount more processing to operate.

the index handing and manipulation modules - isnode, isgrow and
isprune - all adhere to this standard. the decision as to which
handling method to apply is made at the top level, eliminating the
need for myriad if-then-else tests during processing.


----------------------------------------------------------------------
error handling
----------------------------------------------------------------------

the new library deals with errors via setjmp/longjmp. each external
entry point is responsible for initialising a jump buffer and mode
flag in the file descriptor. when an error is detected the thread
is passed to an error handling routine which sets the error codes
and drops the index locks before returning control the entry call.

the error handling routine is also responsible for clearing the
update buffers when triggered in write mode.

the nature of setjmp/longjmp means that it appears to the calling
function as if the ISFAIL call, made initially to initialise the
jump buffer, had returned TRUE.


---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

dcheck
---------------------------------------------------------------------

dcheck - isam file integrity check/repair utility

usage - dcheck [-hifbB] [...]

options - h - display isam header information only
i - just check indexes, ignore data file
f - fix corrupt indexes
b - rebuild all indexes
B - rebuild specific index

the option string, preceded by a dash, can be placed anywhere on the
command line. all options must be specified in one string, and all
options apply to all files specified.

the -B option is a little different. it can be specified multiple
times, and each occurance must be followed by an index number. a
value of 1 denotes the primary index, 2 the next, etc. you cannot
specify -B on multiple files.

dcheck is not interactive, and will ask no questions, so it can be
safely used in batch and script files without operator intervention.

dcheck has been designed to run co-operatively ( unless -f or -b
specified ) on files in active use, but note that other processes
will be blocked for the duration of some of the check cycles.


---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------
Back to top

dreport
---------------------------------------------------------------------

dreport - create .xml, .csv or .txt output from isam data

usage - dreport

dreport takes an .xml format input file that provides the report details,
see export/samples directory for sample input files, and produces output based
on the input file specifications. dreport allows for isam file cross reference,
and filtering of data.

sample tests provided in the export directory.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------
Back to top

dsplit
---------------------------------------------------------------------


dpack - isam file split utility

usage - dsplit [...]

dpack takes an isam file and will split the original file into two
smaller isamfiles, each with the same name as the original for the
prefix but with a 1 and 2 appended to the original name.
it works by building two temporary copies of the original file
and copying half the active data records into filename1 and the
second half into filename2. dsplit can be compiled to delete the
original fileset by adding a #define REMOVE to the code before compiling.

the temporary files are created in the same directory as the original.

you must ensure that you have write permission on the data directory
and that there is enough room for dpack to build the working copies.

dpack will fail if it cannot obtain an exclusive lock on the file.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

dstats
---------------------------------------------------------------------


dstats - report library statistics - expiration date, compilation date
and client limit
usage - dstats

dlist makes use of the isLibInfo() or islibinfo() functions to load
and report some library statistics. dstats is only useful if it is
recompiled and relinked when ever the library is recompiled, to ensure
that the statistics reported are current.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

isconfig.h ISEXTENDED configuration setting
---------------------------------------------------------------------

defining ISEXTENDED to 1 will ensure the global ispid will
hold the id of the process blocking the lock attempt by the calling
process - ISLOCKING 2 only.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

user info
---------------------------------------------------------------------

two functions

int isUserInfo( struct IsamFile *isam, int mode, char *pad );
int isuserinfo( int isfd, int mode, char *pad );

where pad is a character array of size USERINFOSIZE.

USERINFOSIZE is fixed at ten bytes and should not be changed.

allow the application to store a fixed length ten byte info pad
in the index header of any isam file.

mode has two possible values

ISINPUT load pad from index header
ISOUTPUT write pad to index header

these ten bytes are freely available to any application system
that requires the ability to store additional information about
a given isam file.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

COMPRESS/LCOMPRESS/TCOMPRESS

ISKCOMP 0
due to fixed index file format specifications, a single char is used
to store the number of leading compressed bytes and another to store
the number of trailing compressed bytes. this forces a limitation
of 255 bytes ( max unsigned char ) for compressed key size,
regardless of ISMAXKEY setting to ensure full compression of all
trailing spaces or nulls for TCOMPRESS, and all leading duplicate
characters for LCOMPRESS.

ISKCOMP 1
allows compressed key sizes larger than 255 bytes, but will only
permit partial compression on leading and trailing characters.
a maximum of 255 leading duplicate characters, and 255 trailing
spaces or nulls will be compressed.



---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

index masking
---------------------------------------------------------------------

index masking is a mechanism through which the application can control
which indexes a given record will be stored in. usage is relatively
simple, and best explained by example.

masked files are created by adding ISMASKED to the mode when calling
isBuild or isbuild, and are opened in the same way.

the library will return an EBADARG error if a masked file is opened
without ISMASKED in the mode or ISMASKED is added to the open mode
on an unmasked file.

given a file with three indexes, where a value of 1 represents the
primary, 2 the middle index, and 3 the last, the following call will
add a record to the primary index only:

issetmask( isfd, ISMASK(2) + ISMASK(3) );
iswrite( isfd, record_data );

to rewrite a record such that it will be masked in the primary:

issetmask( isfd, ISMASK(1) );
isrewrite( isfd, record_data );

where isrewrite could also be isrewcurr or isrewrec.

the mask value for the current record can be obtained via a call to

isgetmask( isfd );

record masks must be set explicitly - if reading through a file with
the intention of adjusting mask values you must call issetmask for
each record you wish to change.

files built with masking active will allow multiple copies of
identical indexes to be added to the file. this is to allow the
developer to store different record subsets in separate indexes,
but it is important to note that only the *last* of these indexes
can be accessed via isstart - isindex should be used instead.

BASE: if using the base ( file descriptor ) calls you should enquire
and set the mask values directly, rather than using isgetmask
and issetmask. for example:

if( isam->mask & ISMASK(1) ) /* current record masked in primary */

isam->mask = ISMASK(2) + ISMASK(3); /* mask 2nd and 3rd indexes */


NOTES: masking is a custom extension - files built with ISMASKED are
not cisam compatible.

you should not remove indexes from a masked file once it has
been populated.

as of version 6.1, the flag in the index header that denotes
masked files has been changed - you will need to run fixflags
(in the util directory) to patch older files.

see nullkeys.ref for an alternate method of filtering indexes.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

null key masking
---------------------------------------------------------------------

it is possible to flag indexes such that null keys (those whose value
equates to null) will not be added to the index, and the associated
records will not be accessible via that index,

the default value used to determine if a given key is null is zero,
but this can be modified by adding the value (left shifted by eight)
to the key type field.

the following code constructs a null key index in which a character
field containing all spaces will be considered null:

key->k_flags = ISDUPS + NULLKEY;
key->k_nparts = 1;
key->k_part[0].kp_type = CHARTYPE + ( 32 << 8 );
key->k_part[0].kp_start = 10;
key->k_part[0].kp_leng = 10;

null key indexes are not cisam compatible.

see mask.ref for an alternate method of filtering indexes.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

auto file corruption repair
---------------------------------------------------------------------

index and data file corruptions can occurr if a running process is
aborted mid-stream or if a system failure occurs.

often running dcheck -b or dpack after such a failure can be time
consuming if the effected files are large, not to mention dcheck or dpack
must be run manually for each isam file, first to determine the file
status and then to repair any corruptions.

by setting ISREPAIR to 1 in isconfig.h prior to compiling the library,
Disam will maintain data record images of records being updated,
for the duration of the update. if the update concludes successfully
the image is removed from the file system, however if a system failure
occurs the data image remains on the file system and Disam uses these
images to check and repair the effected index/data records.

this removes the need to rebuild the entire isam file manually, which
can be time consuming.

to enable the auto repair facility:

set ISREPAIR to 1 in isconfig.h prior to compiling the Disam
library

set the repair file path in isport.h - see #define reppath

this tells Disam where to store the data record image files
these files are named as: .rep and are of the format

short int - isam filename/path length
short int - data image length
long int - data record number
char string - isam filename/path
char string - isam data record image

after a system failure all corrupted isam files will be automatically
repaired simply by ensuring a call to isStartup() - base, or isstartup()
- wrap, is included in the application's main startup program prior
to opening any isam files. since only one call to isStartUp()/isstartup()
is enforced, and since absolutely no isam files should be opened or already
open at the time isStartUp()/isstartup() is called the application should
ensure that only one application routine performs the startup/repair.

the following restrictions apply:

i) at no time should isstartup() be called if other processes
are accessing or have open any isam files

ii) only one process should call istartup() immediately after
the system has recovered

iii) at no time should the .rep files be manually removed, unless
dcheck -b or dpack is used in place of calling isstartup()


---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

status variables
---------------------------------------------------------------------

cisam implements a bank of four char fields named isstat1 through
isstat4, primarily for use by isam based COBOL programs.

they are declared and initialised in the wrapper library, but the
code makes no attempt to set or modify the values.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

threadsafe
---------------------------------------------------------------------
this feature owes it's existence to Callum Gibson in australia because
without his Expertise and Advice it would never have been completed.
----------------------------------------------------------------------

support for multi-threading is provided on two levels. the base level
implementation consists of a parallel collection of isam function calls
that operate on file descriptor structures (as opposed to the usual
integer file handles) and, other than requiring that you do not open
the same file more than once in any one process, is fully multi-thread
compatible without the requirement for critical section handling.

the second level option provides full cisam standard compatibility
and operates on the standard integer based file handles and associated
file descriptor table. this option provides critical section (mutex)
handling for protection of the descriptor table and logic to provide
appropriate handling for duplicate opens on the same file within the
same process. the mutex requirement impacts on the efficiency of the
library, but allows the use of the standard interface without losing
functionality. there are two exceptions.

the four global variables - isrecnum, isreclen, iserrno and iserrio
are present and maintained, but should not be considered reliable.
instead you should use the following function call equivalents:

long *isrecnum( int isfd );
int *isreclen( int isfd );
int *iserrno( int isfd );
int *iserrio( int isfd );

note that these functions return pointers rather than values. this
allows the application to both enquire and set the value, as in the
following examples:

if( *is_errno(isfd) == ENOREC ) /* record not found */

*is_recnum(isfd) = saved_record_number;

the other exception applies to building variable length files. the
standard isbuild call requires the use of a global isreclen value,
which is not threadsafe. isvbuild covers this problem by taking
the maximum record length as an additional argument:

isvbuild( char *name, int fixlen, int maxlen, IsKdsc *key, int mode );

NOTE: when using second level support you must call isThreaded()
from your root thread before starting any isam threads - this
will initialise the master mutex lock.

NOTE: at no time, under any circumstances, should the application
allow more than one thread to operate on an individual isam
file handle at any given time.

NOTE: isCleanup and iscleanup are inherently not threadsafe - they
should only ever be called by the root thread after all isam
handling threads have terminated.

NOTE: the transaction processing module is still not threadsafe.
we apologise for the inconvenience and hope to have a
solution in the near future.

NOTE: second level threadsafe under os2/warp is only marginally
supported. there are a number of limitations imposed by the
fact that os2 only provides one critical section lock per
thread. at time of writing the library will occasionally
deadlock under heavy use. we are researching a solution to
this problem but at the same time are hoping that ibm will
improve threaded support before it becomes an issue. if you
require second level threadsafe operation under os2 please
stand up and be counted by contacting the support department.

---------------------------------------------------------------------
installation
---------------------------------------------------------------------

in order to make use of the base level implementation, the only thing
you need to do is to compile a library with the ISADMIN feature turned
off. this is because the administration functions make use of global
tables which would not be safe in a non-mutexed environment. use of
this implementation implies that you will be making base level calls
(as detailed in base.ref) and do not intend to allow your applications
to open the same file more than once.

to build a second level library you will need to turn the ISADMIN
feature on, and make a choice from the four options currently given
in isconfig.h as to which ISTHREADED flavour your target will use.
so far we have covered SunOS, Solaris, NT and OS2(unstable).
we hope to add support for MIT pthreads and the win32 threading
extensions soon, and would be most interested to hear from anyone
who would be willing to advise on, or help to test these.

if your thread handling library uses a different series of calls than
those covered, you might wish to take a look at isthread.h, since the
porting procedure is relatively simple. in all cases we will be glad
to offer advice in exchange for the opportunity to add more platforms
to the list of those supported.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top

variable length records
---------------------------------------------------------------------

refer to install.ref for activation and configuration details.

the following is a list of the functional and programmatic differences
between fixed length and variable length isam file handling.

isreclen is a global integer used to pass variable length info around
in much the same way as isrecnum.

isaddindex
the parts of any key added must reside within the fixed length part
of the record.

isbuild
you can add ISVARLEN to the mode argument to create a varlen file.
if so then the record length argument must define the maximum possible
length of the records. you must also set isreclen to the size of the
fixed length header portion of the record. key fields can only reside
in the fixed length portion. you can also use ISVARCMP in place of
ISVARLEN to specify that RLE compression be applied to the data.

isvbuild
isvbuild should be used in place of isbuild if you are creating
variable length files in a multithreaded environment - refer to
thread.ref for details.

isindexinfo
if file is variable, the msb of di_nkeys will be set to indicate same.
di_recsize contains the maximum record size, the fixed length size is
returned in isreclen.

isopen
if the file is variable length you must use ISVARLEN in the mode, or
else isopen will return an EBADARG error. the converse is also true -
if the file is not variable length, then specifying ISVARLEN will
return the same error. if successful then isreclen will be set to the
maximum record length of the opened file.

to get around the inconvenience of the above, you can use ISNOCARE
in the open mode, in which case the file will be opened regardless
of whether it is variable or fixed length. you can then check the
open mode value to determine which kind of file was opened. this
is found in isam->openmode if you are using the base library calls,
or loaded by means of isgetmode( int isfd, int *mode ) if using
the wrapper library.

isread
isreclen will be set to the actual size of the record just read.

isrewcurr
isrewrec
isrewrite
iswrcurr
iswrite
set isreclen to actual size of record before calling.

---------------------------------------------------------------------
compression
---------------------------------------------------------------------

the library provides optional RLE compression on the variable length
portion of the data record. this is specified when creating the file
by using a mode flag of ISVARCMP in place of ISVARLEN. note that
ISVARCMP and ISVARLEN are NOT additive - you must use one or the
other, not both.

once a compressed varlen file has been created, you can use either
ISVARLEN or ISVARCMP when opening the file - either will work, and
the file will be opened in the appropriate mode.

note that RLE encoding is only valuable if your data has a fair
distribution of repeated zero (0), decimal zero (48), or space (32)
bytes.

compression is transparent to the application - records are written
and read as before.

compression is not cisam compatible.

---------------------------------------------------------------------
notes
---------------------------------------------------------------------

the check utility will analyse and test the variable length storage
nodes and report statistics.

---------------------------------------------------------------------
Worldwide Copyright (c) Byte Designs Ltd (2009)
---------------------------------------------------------------------

Back to top