Itzam/Core

C API Documentation (General)



 

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
 

The following elements provide common types, enumerations, and functions used throughout Itzam Core.
 

Types and Structures

itzam_ref

By default, an itzam_ref is the address (position) of information inside an Itzam-defined database. By default, Itzam uses 32-bit file pointers; defining the preprocessor macro ITZAM64 during compilation will create an Itzam library that uses 64-bit file pointers. The 32-bit file operations handle files with sizes up to 2,147,483,648 bytes (some file systems may impose a lower limit); using 64-bit file operations allows access to files up to 9,223,372,036,854,775,808 bytes long (again, limited by file system).

Using 64-bit file pointers will support the growing size of databases and 64-bit CPUs. Handling 64-bit values imposes a slight performance and has a significant affect on file size.

  #if defined(ITZAM64)
    typedef int64_t itzam_ref;
  #else
    typedef int32_t itzam_ref;
  #endif

itzam_int

An itzam_int is the same type as itzam_ref, but used in a different context. While an itzam_ref is a file pointer, and itzam_int is a length, such as the size of a record.

  #if defined(ITZAM64)
    typedef int64_t itzam_int;
  #else
    typedef int32_t itzam_int;
  #endif

itzam_state

Most Itzam functions return a status code, which can be set to ITZAM_OKAY, ITZAM_NOT_FOUND, or any of the other constants found in itzam.h. Note that many functions will call an error handler function for serious errors; itzam_state is designed for programatic purpose (e.g., discovering that a key was not found), as opposed to error handling.

typedef enum
{
    ITZAM_OKAY,
    ITZAM_AT_END,
    ITZAM_AT_BEGIN,
    ITZAM_UNKNOWN,
    ITZAM_NOT_FOUND,
    ITZAM_DUPLICATE,
    ITZAM_32BIT_OVERFLOW
} itzam_state;

itzam_error

When Itzam encounters a serious probled, it calls the error handler defined for a given itzam_datafile. This enumeration identifies the problem.

typedef enum
{
    ITZAM_ERROR_SIGNATURE,
    ITZAM_ERROR_VERSION,
    ITZAM_ERROR_WRITE_FAILED,
    ITZAM_ERROR_OPEN_FAILED,
    ITZAM_ERROR_READ_FAILED,
    ITZAM_ERROR_CLOSE_FAILED,
    ITZAM_ERROR_SEEK_FAILED,
    ITZAM_ERROR_TELL_FAILED,
    ITZAM_ERROR_DUPE_REMOVE,
    ITZAM_ERROR_FLUSH_FAILED,
    ITZAM_ERROR_TOO_SMALL,
    ITZAM_ERROR_NULL_ALLOC,
    ITZAM_ERROR_PAGE_NOT_FOUND,
    ITZAM_ERROR_LOST_KEY,
    ITZAM_ERROR_KEY_NOT_WRITTEN,
    ITZAM_ERROR_KEY_SEEK_FAILED,
    ITZAM_ERROR_ITERATOR_COUNT
} itzam_error;

itzam_error handler

This type defines the signature of an error handling function.

typedef void itzam_error_handler(const char * function_name, itzam_error error);

Functions

itzam_get_state_description

Retrieves a constant static string that describes an Itzam state.

const char * itzam_get_state_description(itzam_state state);

Parameters
state - The state for which a descriptive string is desired

Return Value
A constant static string corresponding to state.

itzam_set_default_error_handler

Sets the default error handler. When Itzam creates a new datafile, it assigns the default handler to the datafile object. You can change the default handler with this function, or set datafile-specific error handlers with itzam_datafile_set_error_handler. The default error handler displays a message to stderr and causes program termination.

void itzam_set_default_error_handler(itzam_error_handler * error_handler);

Parameters
error_handler - Address of user-defined error handler

Return Value
None

itzam_get_default_error_handler

Returns the address of the current default error handler.

itzam_error_handler * itzam_get_default_error_handler();

Parameters
None

Return Value
The address of the current default error handler.