20.1.28 ead_get_group_next_key() (acquires the next key with group specification)

(1) Description

This function acquires the key that immediately follows a specified key in ascending order based on its ASCII code value from among all the keys that belong to a specified group. The keys that belong to the groups under the specified group's hierarchy are also subject to this acquisition processing.

If the specified key does not exist on the connection-target EADS server, the function similarly acquires the key that immediately follows the specified key.

To Page Top

(2) Format

#include <eads.h>
char* ead_get_group_next_key
(
  const EAD_CACHE     *cp,            /* In */
  const char          *group_name,    /* In */ 
  const char          *key,           /* In */
  int                 *error_code     /* Out */
);

To Page Top

(3) Arguments

cp

Specifies the handle (pointer) to the cache in which the key is to be acquired.

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

group_name

Specifies a group name.

For details about the data that can be specified, see 15.2.2(2) Data that can be specified as group names.

key

Specifies the reference key.

For details about the data types that can be specified, see 15.2.2(1) Data types that can be specified as 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

This function returns the key that immediately follows the specified key in ascending order based on its ASCII code value from among all the keys that belong to the specified group.

The function returns NULL in the following cases:

• No key follows the specified key.

• Acquisition of the key failed due to an error.

To Page Top

(5) Notes

• If acquisition of the key is successful (the return value is not NULL), the memory area 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.

• This function determines the connection-target EADS server based on the specified group.

• The EADS server that stores the keys belonging to the specified group might change due to isolation, restoration, or addition (scale-out) processing on EADS servers other than the connection-target EADS server. Therefore, if you have obtained the first key by executing ead_get_group_first_key(), connection might be established with a different EADS server.

• Because groups are not locked on EADS servers, keys that belong to groups might be inserted or deleted by another process after ead_get_group_first_key() or ead_get_group_next_key() has executed.

To Page Top