An Embeddable NoSQL Database Engine

Star

Follow @symisc

Tweet

Follow @unqlite_db

This is a list of compile-time directives and numeric constants used by UnQLite and represented by #defines in the unqlite.h header file. These constants are things such as numeric return parameters from various interfaces.

Result codes

Most of the UnQLite public interfaces return an integer result code from the set shown here in order to indicates success or failure. New error codes may be added in future versions of UnQLite.

/* Standard UnQLite return values */

#define UNQLITE_OK               /* Successful result */

/* Beginning of error codes */

#define UNQLITE_NOMEM            /* Out of memory */

#define UNQLITE_ABORT            /* Another thread have released this instance */

#define UNQLITE_IOERR            /* IO error */

#define UNQLITE_CORRUPT          /* Corrupt pointer */

#define UNQLITE_LOCKED           /* Forbidden Operation */

#define UNQLITE_BUSY             /* The database file is locked */

#define UNQLITE_DONE             /* Operation done */

#define UNQLITE_PERM             /* Permission error */

#define UNQLITE_NOTIMPLEMENTED   /* Method not implemented by the underlying Key/Value storage engine */

#define UNQLITE_NOTFOUND         /* No such record */

#define UNQLITE_NOOP             /* No such method */

#define UNQLITE_INVALID          /* Invalid parameter */

#define UNQLITE_EOF              /* End Of Input */

#define UNQLITE_UNKNOWN          /* Unknown configuration option */

#define UNQLITE_LIMIT            /* Database limit reached */

#define UNQLITE_EXISTS           /* Records exists */

#define UNQLITE_EMPTY            /* Empty record */

#define UNQLITE_COMPILE_ERR      /* Compilation error */

#define UNQLITE_VM_ERR           /* Virtual machine error */

#define UNQLITE_FULL             /* Full database (unlikely) */

#define UNQLITE_CANTOPEN         /* Unable to open the database file */

#define UNQLITE_READ_ONLY        /* Read only Key/Value storage engine */

#define UNQLITE_LOCKERR          /* Locking protocol error */

UNQLITE_OK indicates successful result. Any other return value indicates failure and the caller should handle the error. For a human-readable error message, the client can extract the database error log via unqlite_config() with a configuration verb set to UNQLITE_CONFIG_ERR_LOG.

The UNQLITE_COMPILE_ERR and UNQLITE_VM_ERR error codes are only returned by a call to one of the compile interfaces such as unqlite_compile() or unqlite_compile_file().

UNQLITE_COMPILE_ERR is returned if a compile-time error is encountered during compilation of the target Jx9 script. In which case, the caller must fix its erroneous Jx9 code and call the compile interface again. Note that the compile time error log can be extracted via unqlite_config() with a configuration verb set to UNQLITE_CONFIG_JX9_ERR_LOG.

UNQLITE_VM_ERR is returned if there is a problem related to the initialization of the UnQLite virtual machine (unqlite_vm) after successful compilation of the target Jx9 script. This problem is generally due to a memory failure, but remember running out of memory is a very unlikely scenario on modern hardware even on modern embedded systems.

UNQLITE_READ_ONLY is returned if the underlying Key/Value storage engine only support read-only operations or the database was opened with read-only privileges.

UNQLITE_BUSY is returned if another thread or process have a reserved or exclusive lock on the database. In which case, the caller should wait until the lock holder relinquish it. Many public interfaces return this error code such as: unqlite_kv_store(), unqlite_kv_append(), unqlite_kv_delete(), unqlite_vm_exec() and so forth.

UNQLITE_NOTIMPLEMENTED is returned if the underlying KV storage engine does not implement the target method. For example, the xAppend() method for unqlite_kv_append(), xStore() for unqlite_kv_store(), xDelete() for unqlite_kv_delete() and so forth.

UNQLITE_NOMEM is returned when UnQLite is running out of memory. Again, this is a unlikely scenario on modern hardware.

UNQLITE_ABORT can be returned from the body of an installed foreign function to stop program execution and thus to mimic the Jx9 die construct. This error code can also be returned from one of the public interfaces if and only if the library was compiled with threading support and the given unqlite or unqlite_vm pointer have been released by another thread.

Compile-Time options for The UnQLite Library

For most purposes, UnQLite can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to omit UnQLite features (resulting in a smaller compiled library size) or to change the default values of some parameters.

Every effort has been made to ensure that the various combinations of compilation options work harmoniously and produce a working library.

UNQLITE_ENABLE_THREADS

This option controls whether or not code is included in UnQLite to enable it to operate safely in a multithreaded environment. The default is not. All mutexing code is omitted and it is unsafe to use UnQLite in a multithreaded program. When compiled with the UNQLITE_ENABLE_THREADS directive enabled, UnQLite can be used in a multithreaded program and it is safe to share the same virtual machine and database handle between two or more threads.

The value of UNQLITE_ENABLE_THREADS can be determined at run-time using the unqlite_lib_is_threadsafe() interface.

When UnQLite has been compiled with threading support then the threading mode can be altered at run-time using the unqlite_lib_config() interface together with one of these verbs:

UNQLITE_LIB_CONFIG_THREAD_LEVEL_SINGLE

UNQLITE_LIB_CONFIG_THREAD_LEVEL_MULTI

Platforms others than Windows and UNIX systems must install their own mutex subsystem via unqlite_lib_config() with a configuration verb set to UNQLITE_LIB_CONFIG_USER_MUTEX. Otherwise the library is not threadsafe.

Note that you must link UnQLite with the POSIX threads library under UNIX systems (i.e: -lpthread).

Options To Omit/Enable Features

The following options can be used to reduce the size of the compiled library by omitting optional features. This is probably only useful in embedded systems where space is especially tight, as even with all features included the UnQLite library is relatively small. Don't forget to tell your compiler to optimize for binary size! (the -Os option if using GCC). Telling your compiler to optimize for size usually has a much larger impact on library footprint than employing any of these compile-time options.

JX9_DISABLE_BUILTIN_FUNC

Jx9 is shipped with more than 312 built-in functions suitable for most purposes like string and INI processing, ZIP extracting, Base64 encoding/decoding, JSON encoding/decoding and so forth.

If this directive is enabled, then all built-in Jx9 functions are omitted from the build. Note that special functions such as db_create(), db_store(), db_fetch(), etc. are not omitted from the build and are not affected by this directive.

JX9_ENABLE_MATH_FUNC

If this directive is enabled, built-in math functions such as sqrt(), abs(), log(), ceil(), etc. are included in the build. Note that you may need to link UnQLite with the math library in same Linux/BSD flavor (i.e: -lm).

JX9_DISABLE_DISK_IO

If this directive is enabled, built-in VFS functions such as chdir(), mkdir(), chroot(), unlink(), sleep(), etc. are omitted from the build.

UNQLITE_ENABLE_JX9_HASH_IO

If this directive is enabled, built-in hash functions such as md5(), sha1(), md5_file(), crc32(), etc. are included in the build.