20.1.14 ead_get_all() (acquires values by using a batch operation)

(1) Description

Using a batch operation, this function acquires the values associated with a specified list of keys.

If the same key is specified multiple times, it is processed multiple times in the order specified in the list of keys.

To Page Top

(2) Format

#include <eads.h>
ead_get_all_results ead_get_all
(
  const EAD_CACHE     *cp,           /* In */
  const ead_keys      *keys,         /* In */
  int                 *error_code    /* Out */
);

To Page Top

(3) Arguments

cp

Specifies the handle (pointer) to the cache where the values to be acquired are stored.

Specify the handle (pointer) obtained from ead_start_cache() when access to the cache was started.

keys

Specifies a list of keys (ead_keys structure) that are associated with the values to be acquired.

For details about the data types that can be specified, see 15.2.2(1) Data types that can be specified as keys.

For details about the ead_keys structure and its format, see 20.1.41 ead_keys structure (multiple keys).

error_code

Specifies the pointer from which to retrieve the error code.

For details about error codes, see 20.2 Error codes in the client library (C).

To Page Top

(4) Return value

Using a batch operation, this function returns the results (ead_get_all_results structure) of acquiring the values associated with the specified list of keys.

• If the batch acquisition processing was successful

  The values member contains the values that correspond to the list of keys specified in the argument.

• If the batch acquisition processing failed partially

  The failure_info member contains as many sets of information about failed processing as indicated in the failure_operation_number member.

  At the position of a values member that corresponds to a key whose acquisition failed, an ead_value_element structure whose value is NULL is returned.

• If the batch acquisition processing failed entirely

  The values_length member contains 0, and the values member contains NULL.

• If an error occurred during non-key processing (such as an invalid argument or a shortage of memory area)

  A numeric-type member of the ead_get_all_results structure contains 0, and a pointer-type member contains NULL.

For details about the ead_get_all_results structure and its format, see 20.1.44 ead_get_all_results structure (execution results of ead_get_all()).

To Page Top

(5) Notes

• If the batch value acquisition processing fails, this function returns the following error codes:

  • If the batch acquisition processing failed entirely

    EAD_ERROR_BATCH_FAILED_ALL

  • If the batch acquisition processing failed partially

    EAD_ERROR_BATCH_FAILED_PART

• The memory area for storing the results of batch acquisition of values that is returned as the return value is not freed automatically. You must free it in the application program. For details, see 19.1.1(10) Freeing a memory area returned as a return value.

• If the cache operation fails partially, identify which operations have failed from the return value, and then re-execute this function, if necessary.

• Because caches are not locked while operations are ongoing, a target value might be changed by another cache operation during batch operation.

• When batch operations are performed on a large amount of data, a large amount of memory might be required by EADS clients and EADS servers.

• When batch operations are performed on a large amount of data, it might take a long time to complete the processing. To ensure proper operation, make sure that you design a timeout value that is appropriate for the processing time.

To Page Top