14.3.9 listkey (displays a list of keys)
- Organization of this subsection
(1) Description
This subcommand displays a list of keys that are stored in a cache.
(2) Rules
-
You can execute this subcommand when the EADS server is running.
-
This subcommand executes in descending order of the EADS server positions (Position).
-
This subcommand can be executed if the number of keys in the target range does not exceed 1,000, based on a check performed prior to execution of the subcommand.
(3) Format
eztool listkey [-g group-name|-s] [-f maximum-number-of-keys-during-forced-execution]
cache-name
[--format format-name]
[--columns column-name[,column-name]...]
[--filter filter-condition]
[--match matching-condition]
(4) Options and arguments
(a) -g group-name or --group group-name
Specify this option to display only those keys that belong to the specified group.
For details about the data that can be specified as group names, see 15.2.2(2) Data that can be specified as group names.
(b) -s or --single
Specify this option if you want to display only those keys stored on the EADS server on which this subcommand is executed.
(c) -f maximum-number-of-keys-during-forced-execution or --force maximum-number-of-keys-during-forced-execution
Specify this option when the number of keys in the target range is greater than 1,000 and you want to increase the maximum number of keys that can be processed by the subcommand, and then forcibly execute the subcommand.
Note that when this subcommand is executed with the maximum value increased, its processing might not be completed successfully and a large amount of EADS server resources might be used.
You can specify an integer in the range from 1001 to 10000 for the maximum number of keys.
- Important note
-
Consider specifying this option when the number of keys in the target range is not too much greater than 1,000.
-
If the total number of keys stored in any one of the EADS servers does not exceed 1,000, we recommend that instead of executing this operation, you execute the eztool listkey command sequentially on each EADS server with the -s or --single option specified.
-
If the total number of keys that belong to any one of the groups in the highest hierarchy does not exceed 1,000, execute the eztool listkey command with the -g or --group option specified sequentially for each group with the group hierarchy name in the highest hierarchy obtained by using the eztool listgroup command (note that keys that do not belong to groups cannot be checked by this method).
-
(d) cache-name
Specify the name of the cache for which keys are to be displayed.
The following characters are permitted for a cache name:
-
If cache property files were not used to create caches
A maximum of 32 single-byte characters in ASCII codes 0x20 to 0x7E
-
If cache property files were used to create caches
A maximum of 32 single-byte alphanumeric characters (0 to 9, A to Z, and a to z)
(e) --format format-name
For details about this option, see 14.4.2 How to specify the display format.
(f) --columns column-name[,column-name]...
For details about this option, see 14.4.3 How to specify column filters.
(g) --filter filter-condition
For details about this option, see 14.4.4 How to specify row filters.
(h) --match matching-condition
For details about this option, see 14.4.5 How to specify a condition match.
(5) Output example
The following shows output examples of the eztool listkey command's execution results.
For details about the components of the displayed information, see 14.4.1 Components of the displayed information.
![[Figure]](GRAPHICS/ZU111000.GIF)
The following tables list and describe the summary and content information that are displayed.
|
No. |
Summary name |
Description |
|---|---|---|
|
1 |
KeyCount |
Number of keys in the specified range |
|
No. |
Column name |
Description |
|---|---|---|
|
1 |
Server |
EADS server's IP address and port number used to communicate with the EADS clients.# This information is displayed in the following format: IP address:port number |
|
2 |
Position |
Location (hash value) of an EADS server# |
|
3 |
ID |
EADS server ID# |
|
4 |
Key |
Keys in the specified range |
- Notes:
-
The execution results are displayed according to the following priorities:
-
The results are displayed in descending order of the Position values.
-
The rows with the same Position value are displayed in natural order of the Key values.
-
- #
-
If the execution results contain multiple cells with the same value consecutively, only the first such cell is displayed and the other cells are omitted.
(6) Return code
The following table lists the return codes that this subcommand returns.
|
No. |
Return code |
Description |
|
|---|---|---|---|
|
eads.command.compat parameter omitted in the command properties |
0300 specified in the eads.command.compat parameter in the command properties |
||
|
1 |
0 |
0 |
Command execution was successful. |
|
2 |
101 |
101 |
Initialization of the command failed. |
|
3 |
120 |
The command failed due to a syntax error. |
|
|
4 |
150 |
The command failed during execution. |
|
|
5 |
200 |
The command failed due to a timeout. |
|
- When the --match option is specified:
-
If the condition was satisfied, the subcommand returns 0; otherwise, the subcommand returns 1. If the command's execution failed, the return code is the same as when the --match option is not specified.
(7) Notes
-
This subcommand enables you to check a list of keys without having to create an application program. However, if the number of keys in the target range exceeds 1,000, you need to create an application program.
-
If keys are added while this subcommand is executing, the following occurs, depending on the area where the added keys are stored:
-
If the added keys are stored in an area for which a list has already been acquired
The added keys are not displayed in the list.
-
If the added keys are stored in an area for which a list of keys has not been acquired
The added keys are displayed in the list.
Note that the number of keys is checked before the list of keys is actually acquired. If a large number of keys are added after that check, the keys that exceed the maximum value are included in the display.
-
-
If the command times out during output processing, the output results might not be complete. The command might time out even if output processing is complete. If this happens, increase the command's timeout value, and then re-execute the command.
-
If a large amount of data is stored, the amount of resources required for processing increases.
-
If EADS servers are added to or restored in the cluster while this subcommand is executing, the added or restored EADS servers are not included as processing targets. As a result, some keys might not be displayed. If this occurs, re-execute the subcommand.