Itzam/Core

C API Documentation (Datafiles)



 

Itzam/C 5.0.0 Download: (tar.gz) (bzip2) (zip) Open Source License (GPL) Non-free, Closed-Source License: $495 Itzam/Sharp 1.0.3 Download: (Windows Set-up Application) Open Source License (GPL) Non-free, Closed-Source License: $395 Itzam/Java 2.2.0 Download: (source) (extension) Open Source License (GPL) Non-free, Closed-Source License: $395

Index

General Types & Functions
Datafiles
About Keys
B-tree Indexes
B-tree Index Cursors
Hash Indexes
Sparse Matrix Indexes
 

An itzam_datafile is a structured data file for storing fixed- or variable-length records; it automatically writes new records in space freed by deleted records. This class is useful without any of the indexing capabilities inherent in itzam_btree. In some applications, it may be practical to store data in individual itzam_datafiles, indexing it via one or more itzam_btrees.

For the purposes of an itzam_datafile, consider "record" to be nothing more than a blob of binary data; the semantics of that "blob" is the province of your program. If you're talking to Itzam from Java, for example, you can serialize objects to and from byte streams stored in an itzam_datafile.

To handle variable-length records, itzam_datafile records the size of each record. When a record is deleted, the space it occupied is marked as empty. The file maintains a linked list of deleted record locations and their sizes.

Inserting a new record involves a traverse of the deleted list, looking for an empty record that is large enough to contain the new information. If the deleted list is empty, or the new record is too large to fit into any open slots, the new object record is appended to the file.

Reusing deleted record space has a drawback: it leaves dead space in the file when a newly-inserted record is smaller than the "deleted" space it overwrites. Deleted records also use space in the file until a new record is written into their location. If your record sizes vary widely, it may make sense to periodically compact the file by removing the wasted space, eliminating deleted records, and regenerating indexes. If your records are fixed-length, the data file shouldn't contain much waste space.

All functions that directly manipulate datafiles follow the naming pattern itzam_datafile_*.

Types and Structures

itzam_datafile

This structure encapsulates the elements used internally by Itzam to manipulate a datafile.

typedef struct
{
  // you can safely ignore the members
}
itzam_datafile;

Functions

itzam_datafile_create

Creates a new, empty data file. This function will automatically delete any file named filename.

itzam_state itzam_datafile_create(itzam_datafile * datafile,
                                  const char * filename);

Parameters
datafile - a pointer to the target itzam_datafile structure

filename - the platform-specific name of the new file

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_open

Opens an existing datafile. The file may be open read-only.

itzam_state itzam_datafile_open(itzam_datafile * datafile,
                                const char * filename,
                                bool read_only,
                                bool recover);

Parameters
datafile - a pointer to the target itzam_datafile structure
filename - platform-specific name of the file to be opened
read_only - determines if the file is opened read-only (writes disallowed) recover - if true, the database will rollback any unfinished transactions; if false, the old journal file will simply be removed

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_state itzam_datafile_close

Closes an open data file. This flushes any remaining data to external storage.

itzam_state itzam_datafile_close(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_set_error_handler

Sets an error handling function specific to a given datafile. If this function is not used, Itzam supplies a default error function, printing an error message to stderr and calling exit(1).

void itzam_datafile_set_error_handler(itzam_datafile * datafile,
                                      itzam_error_handler * error_handler);

Parameters
datafile - a pointer to the target itzam_datafile structure
error_handler - the address of an error handler function

Return Value
None

itzam_datafile_tell

Retrieves the file pointer for a given datafile.

itzam_ref itzam_datafile_tell(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
The position of the file pointer in datafile.

itzam_datafile_seek

Sets the file pointer for a given datafile.

itzam_state itzam_datafile_seek(itzam_datafile * datafile,
                                itzam_ref pos);

Parameters
datafile - a pointer to the target itzam_datafile structure
pos - The new position, as calculated from the beginning of the file

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_rewind

Sets the file pointer to the beginning of the first active (not deleted) record in a datafile.

itzam_state itzam_datafile_rewind(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_skip

Moves a datafile's file pointer to the next active (not deleted) record.

itzam_state itzam_datafile_skip(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_get_next_open

Finds a file pointer that can be used to write a record of length bytes. This will either be a deleted record of at least length bytes, or the end of the datafile.

itzam_ref itzam_datafile_get_next_open(itzam_datafile * datafile,
                                       itzam_int length);

Parameters
datafile - a pointer to the target itzam_datafile structure
length - the required number of bytes

Return Value
The file pointer of the first empty record than can hold length bytes, or ITZAM_NULL_POS if an error occurred.

itzam_datafile_write

Writes a record to the datafile at the current file position. The record will be stored in the first deleted record with adequate space, or it will be written to the end of the file if no adequate deleted record is available.

itzam_ref itzam_datafile_write(itzam_datafile * datafile,
                               const void * data,
                               itzam_int length);

Parameters
datafile - a pointer to the target itzam_datafile structure
data - a pointer to the record being written
length - the number of bytes pointed to by data

Return Value
The file pointer to the beginning of the newly-written record, or ITZAM_NULL_POS if an error occurred.

itzam_datafile_rewrite

Approach with caution. This function write a record to s specified location in a datafile, without any checks for available spaces. The purposes is to rewrite a fixed-length record in its original position, and is used by the B-tree classes to maintain the file pointer links between index pages.

itzam_state itzam_datafile_rewrite(itzam_datafile * datafile,
                                   const void * data,
                                   itzam_int length,
                                   itzam_ref where);

Parameters
datafile - a pointer to the target itzam_datafile structure
data - a pointer to the record being written
length - the number of bytes pointed to by data
where - file pointer where this record should be written

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_read

Reads the record at the current file pointer in the given data file. This function assumes that the file pointer is at the beginning of a valid record.

itzam_state itzam_datafile_read(itzam_datafile * datafile,
                                void * data,
                                itzam_int max_length);

Parameters
datafile - a pointer to the target itzam_datafile structure
data - a pointer to a buffer to contain the read record
length - the maximum number of bytes that can be written to data

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_read_alloc

Reads the record at the current file pointer in the given data file. This function assumes that the file pointer is at the beginning of a valid record. Where itzam_datafile_read requires a pointer to preallocated space, itzam_datafile_read_alloc dynamically allocates record space based on information stored in the record header. The caller is responsible for freeing the memory allocated to data.

itzam_state itzam_datafile_read_alloc(itzam_datafile * datafile,
                                      void ** data,
                                      itzam_ref * length);

Parameters
datafile - a pointer to the target itzam_datafile structure
data - a pointer to a pointer that references the allocated record buffer
length - the number of bytes allocated to data -

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_remove

Deletes the record at the current file pointer in the given data file. This function assumes that the file pointer is at the beginning of a valid record.

itzam_state itzam_datafile_remove(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_commit

Forces the datafile to write all data pending in cache to memory.

itzam_state itzam_datafile_commit(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_lock

Exclusively locks a datafile, preventing other processes or threads form making changes.

bool itzam_datafile_lock(itzam_datafile * datafile, bool read_only);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_unlock

Removes an existi8ng lock from the file.

bool itzam_datafile_unlock(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_transaction_start

Begins a new transaction and locks the file. Until a commit or reollback is performed, all changes to the datafile file are recorded in an external journal file.

itzam_state itzam_datafile_transaction_start(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_transaction_commit

Commits the current transaction, which makes all changes permanent. The temporary journal file is removed, and the file unlocked.

itzam_state itzam_datafile_transaction_commit(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state

itzam_datafile_transaction_rollback

The current transaction is "rolled back", meaning that all changes to the file will be "undone". The temporary journal file is removed, and the file unlocked.

itzam_state itzam_datafile_transaction_rollback(itzam_datafile * datafile);

Parameters
datafile - a pointer to the target itzam_datafile structure

Return Value
ITZAM_OKAY if the function succeeded
ITZAM_UNKNOWN the function failed; datafile is in an unknown state