1. C Key-Value Driver API Reference
  2. Data Operation Functions
  3. kv_execute()

kv_execute()

#include <kvstore.h>

kv_error_t 
kv_execute(kv_store_t *store,
           const kv_operations_t *list,
           kv_operation_results_t **result,
           kv_durability_t durability,
           kv_timeout_t timeout_ms)

Executes a sequence of operations. The operations list is created using kv_create_operations(), and individual steps in the operation sequence are created using functions such as kv_create_delete_op() and kv_create_put_op().

Each operation created for this sequence operates on a single key and matches the corresponding Oracle NoSQL Database operation. For example, the operation generated by the kv_create_put_with_options_op() function corresponds to the kv_put_with_options() function. The argument pattern for creating each operation is similar, but they differ in the following respects:

  • The durability argument is not passed to the operations created for this sequence, because that argument applies to the execution of the entire batch of operations and is passed to this function.

  • Each individual operation indicates whether the entire sequence of operations should abort if the individual operation is unsuccessful.

Note that all of the operations performed under a single call to kv_execute() must share the same major key path, and that major key path must be complete.

Parameters

  • store

    The store parameter is the store handle in which you want to run this sequence of operations.

  • list

    The list parameter is the list of operations. This list structure is allocated using kv_create_operations().

  • result

    The result parameter is a list of operations result. Each element in the results list describes the results of executing one of the operations in the sequence of operations.

    Use kv_operation_results_size() to discover how many elements are in the operation results set.

    To determine if a given operation was successful, using kv_result_get_success(). To determine the version of the key/value pair operated upon by the operation, use kv_result_get_version(). To determine the previous version of the key/value pair before the operation was executed, use kv_result_get_previous_version(). To determine the value of the key/value pair prior to executing the operation, use kv_result_get_previous_value().

    To release the resources used by the results list, use kv_release_operation_results().

  • durability

    The durability parameter identifies the durability policy in use when this sequence of operations is executed. All the operations contained within the specified sequence are executed within the scope of a single transaction that effectively provides serializable isolation. The transaction is started and either committed or aborted by this function. This means the operations are all atomic in nature: either they all succeed or the store is left in a state as if none of them had ever been run at all.

    Durability policies are created using kv_create_durability().

    If this parameter is NULL, the store's default durability policy is used.

  • timeout_ms

    The timeout_ms parameter identifies the upper bound on the time interval, in milliseconds, for processing the sequence of operations. A best effort is made not to exceed the specified limit. If zero, the default request timeout is used.

See Also