An Embeddable Datastore Engine

Vedis C/C++ API Reference - DBM Methods.

Syntax

int vedis_kv_append(vedis *pStore,const void *pKey,int nKeyLen,const void *pData,vedis_int64 nDataLen);
int vedis_kv_append_fmt(vedis *pStore,const void *pKey,int nKeyLen,const char *zFormat,...);

Inside foreign command via call context:

int vedis_context_kv_append(vedis_context *pCtx,const void *pKey,int nKeyLen,const void *pData,vedis_int64 nDataLen);
int vedis_context_kv_append_fmt(vedis_context *pCtx,const void *pKey,int nKeyLen,const char *zFormat,...);

Raw Data store (Append operation).

Description

Write a new record into the database. If the record does not exists, it is created. Otherwise, the new data chunk is appended to the end of the old chunk. You can switch to vedis_kv_store() for an overwrite operation.

vedis_kv_append_fmt() is a work-alike of the "printf()" family of functions from the standard C library which is used to append a small formatted string.

The vedis_context_kv() family of functions is similar to their standard counterpart (i.e. vedis_kv_()) except that they expect a vedis_context pointer as their first argument which mean that they are designed to be invoked only from a foreign command.

Records are stored in the database using whatever organization is required by the underlying Key/Value (KV) storage engine. In some cases such as B+Tree, R+Tree, records are stored in a sort order that you may want to define your own comparison function or hash function for the Hash (Default) KV store (either in-memory or disk based). All of these options can be set via vedis_kv_config().

Parameters

pStore	Vedis datastore handle.
pKey	Record key.
nKeyLen	pKey length. If the nKeyLen argument is less than zero, then pKey is read up to the first zero terminator. If nKeyLen is non-negative, then it is the maximum number of bytes read from pKey.
pData	Record data.
nDataLen	Data length (64-bit integer).

Return value

VEDIS_OK is returned on success. Any other return value indicates failure such as:

VEDIS_BUSY: 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.

VEDIS_READ_ONLY: Read-only Key/Value storage engine.

VEDIS_NOTIMPLEMENTED: The underlying KV storage engine does not implement the xReplace() method.

VEDIS_PERM: Permission error.

VEDIS_LIMIT: Journal file record limit reached (An unlikely scenario).

VEDIS_IOERR: OS specific error. This error is considered harmful and you should perform an immediate rollback via vedis_rollback().

VEDIS_NOMEM: Out of memory (Unlikely scenario). This error is considered harmful and you should perform an immediate rollback via vedis_rollback().

For a human-readable error message, you can extract the database error log via vedis_config() with a configuration verb set to VEDIS_CONFIG_ERR_LOG.