An Embeddable Datastore Engine

Tweet

Follow @Vedis

Syntax

Register a foreign command.

Description

This interface known as foreign command creation routine is used to add new Vedis commands or to redefine the behavior of existing commands. After successful call to this routine, the installed command is available immediately and can be invoked from vedis_exec().

The first parameter is the Vedis handle to which the command is to be added. If an application uses more than one Vedis instance then application-defined commands must be added to each handle separately.

The second parameter is a pointer to a null terminated string holding the name of the command to be created or redefined. A valid command name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. Also note that command names under Vedis are case sensitive.

The third and most important parameter is a pointer to C-language function that implement the foreign command. This function must accept three parameters. The first parameter is a pointer to a vedis_context structure. This is the context in which the command executes.

The application-defined foreign function implementation will pass this pointer through into calls to dozens of interfaces, these includes:

vedis_context_kv_store(), vedis_context_throw_error(), vedis_context_new_scalar(), vedis_context_user_data() and many more.

The computation result (i.e: the return value) of the foreign command can be set via one of these interfaces:

vedis_result_int()

vedis_result_int64()

vedis_result_bool()

vedis_result_double()

vedis_result_null()

vedis_result_string()

vedis_result_value()

vedis_result_string_format()

If no call is made to one of these interfaces, then a NULL return value is assumed. The return value could be extracted later using vedis_exec_result().

The second parameter xCmd() takes is the total number of arguments passed to the foreign command. If the total number of arguments is not the expected one, the command can throw an error via vedis_context_throw_error() as follow:

vedis_context_throw_error(pCtx,VEDIS_CTX_WARNING,"Unexpected number of arguments");

The last parameter xCmd() takes is an array of pointers to vedis_value which represents command arguments. The implementation of the foreign command can extract their contents via one of these interfaces:

vedis_value_to_int()

vedis_value_to_bool()

vedis_value_to_int64()

vedis_value_to_double()

vedis_value_to_string()

The xCmd() implementation must return VEDIS_OK on success. But if the callbacks wishes to abort processing, it must return VEDIS_ABORT instead.

The fourth and last parameter is an arbitrary pointer. The implementation of the command can gain access to this pointer using vedis_context_user_data(). Also note that foreign command can store an arbitrary number of auxiliary private data in a stack-able manner via vedis_context_push_aux_data().

Built-in commands may be overloaded by new application-defined commands. Note that Vedis is shipped with more than 70 built-in commands installed using exactly this interface.

Parameters

pStore	Vedis datastore handle.
zName	A pointer to a null terminated string holding the name of the foreign command.
xCmd	A pointer to a C function performing the desired computation.
pUserDara	Arbitrary user pointer which could be extracted later in the implementation of the foreign command via vedis_context_user_data().

Return value

VEDIS_OK is returned on success. Any other return value indicates failure (i.e. Out of memory).

See also