Defined in file: hzDatabase.h

hdbIsamfile is a memory assisted disk based ordered collection class, designed to store large volumes of data either as a 1:1 or 1:many key-object map or as a key-only set. Both keys and objects are strings and are limited to 256 bytes. The collection is ordered by lexical value. It is anticipated that in most cases, both keys and objects will be small single values such as domain names. However, the strings can also be serialized objects. Epistula for example, uses a hdbIsamfile to store short form messages. The keys or key-object pairs are held within a single large data file, in logical data blocks formed of a variable number of disk blocks. The index is a memory resident map which maps the LOWEST key from from each logical block to the logical block address, this being the position of its first disk block in the data file. The index is rendered persistent by means of a separate index file, which is operated on an always-append basis. The index file is completely read in during initialization. With an SSD, there is no concern regarding read operations but write operations must be minimized to conserve the life of the device. With a standard hard disk all I/O is a performance issue. Either way, write operations in particular must be as few as possible. Clearly retrieval of an item (key or key-object pair), will read at least one disk block unless some form of cache is deployed and the item of interest happens to be in it. It is also clear that until an inserted item is committed to disk, it can be lost in the event of a program crash. However as files are buffered, not all write operations are 'hard'. Data is only written to a disk block when the buffer pointer equates to a block boundary OR a seek operation redeploys the buffer to another block, necessitating the saving of the current buffer content to the current disk block. If all inserts were written to the end of the data file, as the items are small most would not result in a hard write. As the whole point of an ISAM is that items are in key order in the data file, the advantage of file buffering is lost. To overcome this difficulty, hdbIsamfile has an optional auxillary memory resident map for pending items which is backed up to file that is always appeneded. This auxillary will map items to the logical block addresses where they would be inserted. Then at a suitable point, the pending items are which directly maps keys ...

Constructors/Detructors

hdbIsamfile*hdbIsamfile(void)
NULL-TYPEhdbIsamfile(void)
void~hdbIsamfile(void)
NULL-TYPE~hdbIsamfile(void)

Public Methods:

hzEcodeClose(void)Close the datacron. Arguments: None
hzEcodeDelete(hzString& key)Delete an object from the datacron. This function appears only for consistency with the base class and does nothing.
boolExists(hzString& key)Determine if the supplied key matches any found in the ISAM
hzEcodeFetch(hzArray<hzPair>& result)hzString& keyLo, hzString& keyHi, Fetches objects matching the key or falling within a range of two keys.
hzEcodeInit(hdbADP& adp)hzString& name, hzString& opdir, uint32_t keySize, uint32_t objSize, uint32_t blkSize, Initialize the hdbIsamfile instance. This is a matter of asserting the working directory, the index and the data file. exist and are open for reading and writing. This is a matter of opening an input stream for the data file, an output stream for the data file and an output stream for the index file. Note both the output streams are opened with ios::app as they will only ever append and that there is no input stream for the index file as during normal operation of a binary datacron, the index is never read. nd index file as append only files. The first step is to open the index file for reading and load the index into the memory. This file is then closed but opened again in write mode. If it does not exists then it is created and left open in write mode. The second step is to create or open the data file for both reading and writing. The hdbIsamfile is then ready to store and retrieve binary objects. Errors: Any false return is due to an irrecoverable error. The calling function must check the return value.
hzEcodeInsert(hzString& newKey)hzString& newObj, Insert a key/object pair into the ISAM file. Note it is permissable for the object to be blank but not the key. This involves the following steps:- - Identify the target data block for the new key from the index. We then have both the target block address and the available space. - Read in target data block, assemble new version of it including the new key. - If the target has enough space - Write out target block. - Advice the index map of a new higher key, if applicable. - Else - Write out half the target to the original location - Write out upper half to a new location - Advice the index map. Note that no attempt is made to move elements into adjacent data blocks. Disk space is cheap but disk operations are expensive.
hzEcodeOpen(void)Open the hdbIsamfile instance. This is a matter of opening an input stream for the data file, an output stream for the data file and an output stream for the index file. Note both the output streams are opened with ios::app as they will only ever append and that there is no input stream for the index file as during normal operation of a hdbIsamfile, the index is never read. Arguments: None

Member Variables:

char*m_BufOperational buffer
hzEcodem_CondError condition
hzChainm_ErrorError report
hzMapM<hzString,uint32_t>m_IndexOperaional map
hzStringm_NameBasename
ifstreamm_RdDData file input stream for Fetch
hzStringm_WorkdirWorking directory
ofstreamm_WrDData file output stream for Insert/Update
ofstreamm_WrIIndex file output stream for Insert/Update
hzStringm_fileDeltaName of delta file
hzStringm_fileStoreName of data file
uint16_tm_nBlkSizeLogical data block size
uint32_tm_nBlocksNumber of file system blocks in data file
uint32_tm_nElementsTotal number of elements (keys or key-object pairs)
uint16_tm_nInitStateInitialization state
uint16_tm_nKeyLimitMax size of key (max 256 bytes)
uint16_tm_nObjLimitMax size of object (max 256 bytes)