An Embeddable Datastore Engine

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

Syntax

int vedis_kv_fetch_callback(
      vedis *pStore,
    const void *pKey,int nKeyLen,
      int (*xConsumer)(const void *pData,unsigned int iDataLen,void *pUserData),
      void *pUserData
);

Inside foreign command via call context:

int vedis_context_kv_fetch_callback(
      vedis_context *pCtx,
    const void *pKey,int nKeyLen,
      int (*xConsumer)(const void *pData,unsigned int iDataLen,void *pUserData),
      void *pUserData
);

Fetch a raw record from the database and invoke the supplied callback.

Description

This is the recommended interface to use by clients for data extraction. Rather than allocating a static or dynamic buffer (Inefficient scenario for large data), the caller simply need to supply a consumer callback which is responsible of consuming the record data perhaps redirecting it (i.e. Record data) to its standard output (STDOUT), disk file, connected peer and so forth (See example below).

Depending on how large the extracted data, the callback may be invoked more than once.

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.

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.
int (xConsumer)( const void pData, unsigned int iDataLen, void *pUserData )	Data consumer callback. The callback must accept three arguments: The first argument is a pointer to the extracted data chunk. The second argument is the length in bytes of the extracted chunk. The last argument is a copy of the pointer (callback private data) passed as the fifth argument to this routine. When done, the callback must return VEDIS_OK. But, if for some reason the callback wishes to abort processing and thus to stop its invocation, it must return VEDIS_ABORT instead.
pUserData	Arbitrary user pointer which is forwarded verbatim by the engine to the callback as its third argument.

Return value

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

VEDIS_NOTFOUND: Nonexistent record.

VEDIS_BUSY: Another thread or process have an exclusive lock on the database. In this case, the caller should wait until the lock holder relinquish it.

VEDIS_IOERR: OS specific error.

VEDIS_NOMEM: Out of memory (Unlikely scenario).

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.