Create/Update

Detailed Description

Set the value of a document.

Functions
lcb_error_t	lcb_store3 (lcb_t instance, const void *cookie, const lcb_CMDSTORE *cmd)
	Schedule a single storage request. More...

Macros
#define	LCB_CMD_SET_VALUE(scmd, valbuf, vallen)
	Set the value buffer for the command. This may be used when the new value is a single contiguous buffer. More...
#define	LCB_CMD_SET_VALUEIOV(scmd, iovs, niovs)
	Set value from a series of input buffers. This may be used when the input buffer is not contiguous. Using this call eliminates the need for creating a temporary contiguous buffer in which to store the value. More...

Enumerations
enum	lcb_storage_t
	Values for lcb_CMDSTORE::operation. More...

Function Documentation

lcb_error_t lcb_store3	(	lcb_t	instance,
		const void *	cookie,
		const lcb_CMDSTORE *	cmd
	)

Schedule a single storage request.

Stability

Committed:

Parameters

instance	the handle
cookie	pointer to associate with the command
cmd	the command structure

Returns

LCB_SUCCESS on success, error code on failure

Request

lcb_CMDSTORE cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "Key", 3);
LCB_CMD_SET_VALUE(&cmd, "value", 5);
cmd.operation = LCB_ADD; // Only create if it does not exist
cmd.exptime = 60; // expire in a minute
lcb_store3(instance, cookie, &cmd);
lcb_wait3(instance, LCB_WAIT_NOCHECK);

### Response

lcb_install_callback3(instance, LCB_CALLBACK_STORE, store_callback);
void store_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
{
    if (rb->rc == LCB_SUCCESS) {
        printf("Store success: CAS=%llx\n", rb->cas);
    } else {
        printf("Store failed: %s\n", lcb_strerorr(NULL, rb->rc);
    }
}

Operation-specific error codes include:

• LCB_KEY_ENOENT if LCB_REPLACE was used and the key does not exist
• LCB_KEY_EEXISTS if LCB_ADD was used and the key already exists
• LCB_KEY_EEXISTS if the CAS was specified (for an operation other than LCB_ADD) and the item exists on the server with a different CAS
• LCB_KEY_EEXISTS if the item was locked and the CAS supplied did not match the locked item's CAS (or if no CAS was supplied)
• LCB_NOT_STORED if an LCB_APPEND or LCB_PREPEND operation was performed and the item did not exist on the server.
• LCB_E2BIG if the size of the value exceeds the cluster per-item value limit (currently 20MB).

Note

After a successful store operation you can use lcb_endure3_ctxnew() to wait for the item to be persisted and/or replicated to other nodes.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

---

Data Structure Documentation

struct lcb_CMDSTORE

Command for storing an item to the server.

This command must contain the key to mutate, the value which should be set (or appended/prepended) in the lcb_CMDSTORE::value field (see LCB_CMD_SET_VALUE()) and the operation indicating the mutation type (lcb_CMDSTORE::operation).

Warning

exptime cannot be used with operation set to LCB_APPEND or LCB_PREPEND.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

Data Fields
lcb_U32	cmdflags	Common flags for the command. These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.
lcb_U32	exptime	Specify the expiration time. This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.
lcb_U64	cas	The known CAS of the item. This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.
lcb_KEYBUF	key	The key for the document itself. This should be set via LCB_CMD_SET_KEY()
lcb_KEYBUF	_hashkey	Stability Volatile:
lcb_VALBUF	value	Value to store on the server. The value may be set using the LCB_CMD_SET_VALUE() or LCB_CMD_SET_VALUEIOV() API
lcb_U32	flags	Format flags used by clients to determine the underlying encoding of the value. This value is also returned during retrieval operations in the lcb_RESPGET::itmflags field
lcb_datatype_t	datatype	Do not set this value for now.
lcb_storage_t	operation	Controls how the operation is perfomed. See the documentation for lcb_storage_t for the options. There is no default value for this field.

struct lcb_RESPSTORE

Response structure for lcb_store3()

Data Fields
void *	cookie	Application-defined pointer passed as the cookie parameter when scheduling the command.
const void *	key	Key for request.
lcb_SIZE	nkey	Size of key.
lcb_CAS	cas	CAS for response (if applicable)
lcb_error_t	rc	Status code.
lcb_U16	version	ABI version for response.
lcb_U16	rflags	Response specific flags. see lcb_RESPFLAGS
lcb_storage_t	op	The type of operation which was performed.

Macro Definition Documentation

#define LCB_CMD_SET_VALUE	(		scmd,
			valbuf,
			vallen
	)

Set the value buffer for the command. This may be used when the new value is a single contiguous buffer.

Stability

Committed:

Parameters

scmd	an lcb_CMDSTORE pointer
valbuf	the buffer for the value
vallen	the length of the buffer

The buffer needs to remain valid only until the command is passed to the lcb_store3() function.

Examples:

example/libeventdirect/main.c, and example/minimal/minimal.c.

#define LCB_CMD_SET_VALUEIOV	(		scmd,
			iovs,
			niovs
	)

Set value from a series of input buffers. This may be used when the input buffer is not contiguous. Using this call eliminates the need for creating a temporary contiguous buffer in which to store the value.

Stability

Committed:

Parameters

scmd	the command which needs a value
iovs	an array of lcb_IOV structures
niovs	number of items in the array.

The buffers (and the IOV array itself) need to remain valid only until the scheduler function is called. Once the scheduling function is called, the buffer contents are copied into the library's internal buffers.

Enumeration Type Documentation

enum lcb_storage_t

Values for lcb_CMDSTORE::operation.

Storing an item in couchbase is only one operation with a different set of attributes / constraints.

Enumerator
LCB_ADD	Will cause the operation to fail if the key already exists in the cluster.
LCB_REPLACE	Will cause the operation to fail unless the key already exists in the cluster.
LCB_SET	Unconditionally store the item in the cluster.
LCB_APPEND	Rather than setting the contents of the entire document, take the value specified in lcb_CMDSTORE::value and append it to the existing bytes in the value. This is functionally equivalent to the following: static void get_callback(lcb_t instance, int cbtype, const lcb_RESPBASE *rb) { const lcb_RESPGET *resp = (const lcb_RESPGET *)rb; const char *to_append = "stuff to append"; char *new_value; size_t new_value_len; lcb_CMDSTORE cmd = { 0 }; lcb_IOV iov[2]; cmd.operation = LCB_APPEND; iov[0].iov_base = (void *)resp->value; iov[0].iov_len = resp->nvalue; iov[1].iov_base = (void *)to_append; iov[1].iov_len = strlen(to_append); LCB_CMD_SET_VALUEIOV(&cmd, iov, 2); LCB_CMD_SET_KEY(&cmd, resp->key, resp->nkey); lcb_store3(instance, NULL, &cmd); }
LCB_PREPEND	Like LCB_APPEND, but prepends the new value to the existing value.