Itzam/Core

C API Documentation (matrix Indexes)



 

Itzam/Core 4.0.7 Download: (tar.gz) (bzip2) (zip) Open Source License (GPL) Non-free, Closed-Source License: $749 Itzam/Java 2.1.1 Download: (source) (extension) Open Source License (GPL) Non-free, Closed-Source License: $749 Documents Itzam Home Page C API Documentation Java Class Documentation

Index

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

An itzam_matrix associates records with a column-row coordinate in a two-dimensional grid. In general, the reference is a file pointer that locates an object that "belongs" to the key value—but the reference can be interpretted however you like, given that the index implies no semantics on the 64-bit itzam_ref values associated with keys.

As a convenience, Itzam implements functions that store records in the index file itself, and use the resulting itzam_ref for association with the key. In many case (including the example program), it makes sense to combine the index with records; in other applications, you may want a separate data file indexed by one or more independent indexes. Itzam provides great design flexibility, and can support relational and network database models.

The matrix data structure maintains a grid of keys, with dimensions determined by the programmer.

All functions that directly manipulate matrix indexes follow the naming pattern itzam_matrix_*.

Types and Structures

itzam_matrix

For the most part, you won't directly access the members of an itzam_matrix structure. However, it is possible (and often quite desirable) to store non-index data in the same datafile used by an index. The example program does this very thing, combining contact records with the name-based matrix index.

typedef struct
{
    itzam_datafile * m_datafile;       // file associated with this matrix file
    
    // The rest is internal stuff
}
itzam_matrix;

Functions

itzam_matrix_create

Creates a new matrix index by establishing a data file with a specific internal structure.

itzam_state itzam_matrix_create(itzam_matrix * matrix,
                                const char * filename);

Parameters
matrix - a pointer to the target itzam_matrix structure
filename - the platform-specific name of the file to be created

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

itzam_matrix_open

Opens an existing matrix index file.

itzam_state itzam_matrix_open(itzam_matrix * matrix,
                              const char * filename,
                              bool read_only);

Parameters
matrix - a pointer to the target itzam_matrix structure
filename - the platform-specific name of the file to be opened
read_only - if true, the file will be opened read-only (no writes allowed)

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

itzam_matrix_close

Closes an open matrix file and flushes any remaining file operations.

itzam_state itzam_matrix_close(itzam_matrix * matrix);

Parameters
matrix - a pointer to the target itzam_matrix structure

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

itzam_matrix_get_cols

Get the number of columns in this index.

itzam_int itzam_matrix_get_cols(itzam_matrix * matrix);

Parameters
matrix - a pointer to the target itzam_matrix structure

itzam_matrix_get_rows

Get the number of rows in this index.

itzam_int itzam_matrix_get_rows(itzam_matrix * matrix);

Parameters
matrix - a pointer to the target itzam_matrix structure

itzam_matrix_insert

Adds a new record reference to the index, at the given coordinates. The index does not place any semantics on the value of reference; it is merely stored in association with key. The reference can be a file pointer in matrix->m_datafile or a file position in another datafile, or any other 64-bit value of the caller's choosing.

itzam_state itzam_matrix_insert(itzam_matrix * matrix,
                                itzam_int col,
                                itzam_int row,
                                itzam_ref ref);

Parameters
matrix - a pointer to the target itzam_matrix structure
col - column (x-axis) coordinate
row - row (y-axis) coordinate
reference - a 64-bit value that the user can use to find the record associated with key

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

itzam_matrix_insert_rec

Adds a new record to the index and its associated datafile, associating it with the given coordinates.

itzam_state itzam_matrix_insert_rec(itzam_matrix * matrix,
                                    itzam_int col,
                                    itzam_int row,
                                    const void * record,
                                    itzam_ref rec_len);

Parameters
matrix - a pointer to the target itzam_matrix structure
col - column (x-axis) coordinate
row - row (y-axis) coordinate
record - a pointer to the record data
rec_len - the number of bytes pointed to by record

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

itzam_matrix_read_rec

Reads the record associated with the given coordinates. This function assumes that the record was written to matrix->m_datafile with itzam_matrix_insert_rec or by directly calling itzam_datafile_write.

itzam_state itzam_matrix_read_rec(itzam_matrix * matrix,
                                  itzam_int col,
                                  itzam_int row,
                                  void * record,
                                  itzam_ref max_rec_len);

Parameters
matrix - a pointer to the target itzam_matrix structure
col - column (x-axis) coordinate
row - row (y-axis) coordinate
record - a buffer of at least max_rec_len bytes
max_rec_len - the number of bytes that can be stored in record

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

itzam_matrix_find

Returns the record reference associated with a given coordinates.

itzam_ref itzam_matrix_find(itzam_matrix * matrix,
                            itzam_int col,
                            itzam_int row);

Parameters
matrix - a pointer to the target itzam_matrix structure
col - column (x-axis) coordinate
row - row (y-axis) coordinate

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

itzam_matrix_remove

Removes the first key found that is associated with the given coordinate. If ref is NULL, the function also attempts to remove the associated record from the matrix->m_datafile. If ref is not NULL, this function returns the record reference associated with the deleted key.

itzam_state itzam_matrix_remove(itzam_matrix * matrix,
                                itzam_int col,
                                itzam_int row,
                                itzam_ref * ref);

Parameters
matrix - a pointer to the target itzam_matrix structure
key - a pointer to the key data that identifies the record
ref - see function description above

Return Value
ITZAM_OKAY if the function succeeded
col - column (x-axis) coordinate
row - row (y-axis) coordinate
ITZAM_UNKNOWN the function failed; datafile is in an unknown state