CQDB: CQDB Writer API

The seekable stream must be created by the fopen() function with writable and binary flags ("wb"). The CQDB Writer API can build a CQDB chunk at any position on the stream; one can thus write some data, append a CQDB chunk, and continue writing other data on the stream.

By default, the function cqdb_writer() constructs a database with forward (string to integer identifier) and backward (integer identifier to string) lookups. The data for reverse lookup is omitted with CQDB_ONEWAY flag specified.

It is recommended to keep the maximum number of identifiers as smallest as possible because reverse lookup is maintained by a array with the size of sizeof(int) * (maximum number of identifiers + 1). For example, putting a set of integer identifers (0, 1, 1000) creates a reverse lookup array with 1001 elements only to waste the disk space for 998 (= 1001-3) elements in the array.

Function Documentation

cqdb_writer_t* cqdb_writer	(	FILE *	fp,
		int	flag
	)

Create a new CQDB writer on a seekable stream.

This function initializes a database on the seekable stream and returns the pointer to a cqdb_writer_t instance to write the database. The stream must have the writable and binary flags. The database creation flag must be zero except when the reverse lookup array is unnecessary; specifying CQDB_ONEWAY flag will save the storage space for the reverse lookup array. Once calling this function, one should avoid accessing the seekable stream directly until calling cqdb_writer_close().

Parameters:

	fp	The pointer to the writable and seekable stream.
	flag	Database creation flag.

Return values:

cqdb_writer_t* The pointer to the new cqdb_writer_t instance if successful; otherwise NULL.

int cqdb_writer_close ( cqdb_writer_t * dbw )

Close a CQDB writer.

This function finalizes the database on the stream. If successful, the data remaining on the memory is flushed to the stream; the stream position is moved to the end of the chunk. If an unexpected error occurs, this function tries to rewind the stream position to the original position when the function cqdb_writer() was called.

Parameters:

dbw

The pointer to the cqdb_writer_t instance.

Return values:

int

Zero if successful, or a status code otherwise.

int cqdb_writer_put	(	cqdb_writer_t *	dbw,
		const char *	str,
		int	id
	)

Put a string/identifier association to the database.

This function append a string/identifier association into the database. Make sure that the string and/or identifier have never been inserted to the database and that the identifier is a non-negative value.

Parameters:

	dbw	The pointer to the cqdb_writer_t instance.
	str	The pointer to the string.
	id	The identifier.

Return values:

int

Zero if successful, or a status code otherwise.

CQDB Writer API

Detailed Description

Typedefs

Functions

Function Documentation


Typedefs
typedef tag_cqdb_writer	cqdb_writer_t
	Typedef of a CQDB writer.
Functions
cqdb_writer_t *	cqdb_writer (FILE *fp, int flag)
	Create a new CQDB writer on a seekable stream.
int	cqdb_writer_put (cqdb_writer_t dbw, const char str, int id)
	Put a string/identifier association to the database.
int	cqdb_writer_close (cqdb_writer_t *dbw)
	Close a CQDB writer.