The library is split into two sections - the base and the wrapper.
The base source is found in the base subdirectory, and the wrapper source in wrap. All public header files are in the head directory.
API References
If you plan to use only the base library then you can ignore both the wrap directory and head/iswrap.h
If you are planning to use only the wrapped (cisam™ standard) calls then you should probably compile everything into one library and ignore head/isbase.h entirely.
If you intend to use both flavours, then it might be an idea to build two separate libraries, but this is optional.
Note that if you plan to use the wrapper calls, or the transaction processing module, the base library MUST be compiled with ISADMIN activated.
Before starting you will need to edit isconfig.h and adjust it as appropriate - refer to Configuration below for details.
The source for the dcheck utility is located in the util directory and should be linked with the base library to produce an executable. Documentation is found in dcheck. The same is true for the dpack and dlist utilities.
The test directory contains a collection of benchmark utilities, documented in Regression Test Source
You will find a makefile in the root folder - this is configured to match the source folders as distributed, and will make all targets from the current directory, placing the result in the target folder.
To compile and check disam out of the box
, run:
make clean new lib util test check
in your disam source folder.
#define ISADMIN 1 /* global file administration */
With this option active, the library will maintain an internal table of active isam file descriptors, reuse system file handles when more than one instance of the same isam file is opened, and include the isCleanUp call amongst the library entry points. Admin is mandatory when the standard wrapper library or transaction processing are used, and definitely advisable if you plan to open more than one instance of the same file at any given time.
#define ISAUDIT 1 /* 0:off 1:active */
A value of one includes support for cisam standard audit trail logging, see Audit Trail Mechanism for details.
#define ISLOGGING 1 /* 0:none 1:standard */
A value of one includes support for cisam standard transaction logging and processing, together with a number of enhancements. see Transaction Processing for more details.
NOTE - to use this option you must activate the ISADMIN feature.
NOTE also that transaction processing is currently supported under threads.
#define ISVARIABLE 0 /* 0:none 1:cisam 2:disam 3:huge*/
A value of one includes support for variable length records in the standard cisam compatible configuration.
A value of two provides a better hash table algorithm and finer granularity with regard to the use and reuse of slots in the variable length data storage nodes. both one and two include support for data compression.
A value of three adds the ability to store up to 4294967295 records.
There is a limitation in the original disam/cisam variable length in that the maximum record number that can be stored in the 3 bytes allocated for storing varinfo and continuation node record numbers is 16777216. A value of three removes this limit.
Please see Variable Length Records for more details.
#define ISLOCKING 2 /* 0:none 1:old 2:new 3:lck */
A value of zero will disable locking entirely, resulting in a faster and lighter version of the library, suitable for single user use, or where all media is read only, etc.
Locking one enables the original cisam (prior to version 4) locking algorithm.
Locking two is the current (standard) method used by cisam versions 4 and greater, and may also be faster on some platforms.
Locking three is compatible with the DOS 'third file' locking method, and is provided to allow 'lowest common denominator' NFS concurrency with dos based applications.
Locking one and three rely on the lockf() system call, two requires fcntl().
#define ISDUPLOCKS 1 /* honour locks in dup opens */
Cisam allows the same file to be opened more than once in EXCLLOCK mode within the same process. It also permits the same record to be locked more than one under different filehandles within the same process, not to mention that it is also legal to erase a file that is already open in the current process, after which point any data written to the file will evaporate. Set this to zero for cisam compatible operation, but please be careful..
#define ISDECLARE 1 /* include prototypes */
If non zero then full ANSI standard function prototyping is enabled.
ISDATAVOID
#define ISDATAVOID 0 /* void data pointers */
Cisam insists that all record pointers passed must be char type. if ISDATAVOID is set to one, they will be declared as type void which, under some compilers, will allow you to pass anything without warnings. This feature is compiler dependent.
#define ISCUSTOM 0 /* custom key types */
This option allows the addition of custom key types - refer to Custom Key Types for more details.
#define ISBERKELY 0 /* 0:memcpy() 1:bcopy() */
A value of one uses the berkely memory handling functions bcopy() and bcmp() and covers for the absence of memset() internally. a value of zero uses the default memcpy(), memcmp() and memset() calls.
#define ISLONGID 0 /* allows for long pids */
A value of 1 will override the C-ISAM / X/OPEN spec that forces short integer values to be stored in the transaction processing logfile and audit trail file for pids and uids.
** WARNING ** do not set to 1 if you are expecting C-ISAM/X/OPEN concurrency or file compatibility or if the process ids returned from the system's getpid() function are short values.
#define ISIDXBLK 1024 /* default index block size */
The default index block size to be used when creating isam files. 512 and 1024 are the usual standards. 512 is compatible with older versions of cisam, while 1024 seems to be most common value, and is compatible with current cisam files. 1024 will be enforced when building variable length files, but you can still use other values for your regular data.
#define ISDUPLEN 4 /* default duplicate width */
The width of the field used to store the duplicate sequence numbers in the index. A value of 4 will permit approximately 2000 million identical keys in any given index, while 2 imposes a limit of just over 32500. 4 is more expensive in terms of disk space, so you may wish to consider using 2 if this is important and you not intend to go over the limit. Bear in mind that the limit applies to the max count of an individual identical key, not to the total number of duplicates in the index. 4 is compatible with current cisam, 2 with older versions.
#define ISMAXPATH 1024 /* maximum path len */
The amount of space to allocate and enforce when working on paths.
#define ISMAXIDX 10 /* indexes per file */ #define ISMAXPARTS 10 /* parts per key */ #define ISMAXKEY 128 /* bytes per key */
These set the number of indexes per file, the number of parts per index, and the total allowable byte count per index key. The value of ISMAXPARTS is also available via the standard NPARTS define.
#define ISMAXBUF 20 /* buffers per index */
This is actually a slight misnomer in that the root node is always buffered, so the resultant number of memory allocations will actually be one more than the number you specify here. One important caveat applies - you must specify a value that is at least twice the expected depth of the largest expected index tree.
#define ISERRBASE 500 /* start error codes at */
The library generated iserrno values traditionally start at 100. On most newer platforms this conflicts with system generated errno values. You can use this define to change where the DISAM error codes start.
#define ISTHREADED 0 /* threadsafe handling */
Please refer the Thread Safety for details.
#define ISPURE 0 /* sequential pure indexes */
Set ISPURE to 1 to insert a call to store a sequential value for isrecnum in all pure indexes.