List Clustered Hash Table Keys (QcstListCHTKeys) API

The List Clustered Hash Table Keys (QcstListCHTKeys) API generates a list of keys and descriptive information about the entries stored in the clustered hash table specified by the connection handle parameter. The generated list is placed in the specified user space and replaces any existing list. There is no special authority needed to retrieve a list of the keys. The list can include some of the following:

• All entries
• Entries which are in conflict between clustered hash table domain nodes
• Entries which are owned by a specific user
• Entries which were last stored by a specific user

Restrictions:

• A connection must have been established with the clustered hash table server.
• When this API is called, the clustered hash table server must be active on the requesting node.
• This API must be run under the same job that issued the Connect Clustered Hash Table (QcstConnectCHT) API.

Authorities and Locks

User Space Authority

*CHANGE

User Space Library Authority

*EXECUTE

User Space Lock

*EXCLRD

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The name of the *USRSPC object that is to receive the generated list. The first 10 characters contain the user space object name, and the second 10 characters contain the name of the library where the user space is located. No special values are supported for library name, for example, QTEMP, *CURLIB, or *LIBL. The user space cannot be in an independent auxiliary storage pool.

Format name

INPUT; CHAR(8)

The format of the information returned for each key in the clustered hash table. Possible values are:

CHTL0100

Clustered Hash Table Keys

For more information, see CHTL0100 Format.

Connection handle

INPUT; CHAR(10)

This is an active connection handle for the clustered hash table server. It is obtained by calling the Connect Clustered Hash Table (QcstConnectCHT) API.

Key selection information

INPUT; CHAR(*)

The information that determines the keys to be listed. The format of this information is described in CHTI0100 Format.

Key selection information size

INPUT; BINARY(4)

The size in bytes of the key selection information parameter. If the size is greater than the length of the key selection information format, it must be padded with zeroes.

Key selection information format

INPUT; CHAR(8)

The format of the key selection information parameter. Possible values are:

CHTI0100

The specific information identifying the keys to be listed.

For more information, see CHTI0100 Format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of the Generated Lists

The clustered hash table key list consists of:

• A user space
• A generic header
• An input parameter section
• A header section
• A list data section:
  • CHTL0100 format

For details about the user area and generic header, see User space format for list APIs. For detailed descriptions of the fields in the list returned, see Field Descriptions.

The completion code in the generic header should be checked to determine if the API completed successfully. When you retrieve list entry information from a user space, you must use the length of entry information returned associated with each entry returned. If you do not use the length of entry information the result may not be valid.

Input Parameter Section

An exact copy of the parameters coded in the call to the API.

Header Section

Global information about the clustered hash table keys.

CHTL0100 Format

General information about the clustered hash table keys. Detailed information about a key can be obtained by using the Retrieve Clustered Hash Table Entry (QcstRetrieveCHTEntry) API.

CHTI0100 Format

The following table shows the format of the key selection information parameter for the CHTI0100 format. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Authority access level. This field describes who is allowed to retrieve and update the entry associated with this key. Valid special values are:

Authorization list name. This is the name of the authorization list specified when the cluster hash table server was started. Valid special values are:

Connection handle. This is an active connection handle for the clustered hash table server. It is obtained by calling the Connect Clustered Hash Table (QcstConnectCHT) API.

Entry status. Indicates whether the entry is in conflict or not. An entry is in conflict if it is not the same on all nodes in the clustered hash table domain. A potential cause of an entry marked in conflict is the clustered hash table domain nodes were not communicating and the information associated with the key was updated from more than one cluster partition. For additional details on cluster node partitions, see Partition errors. To resolve an entry in conflict, use the Store Clustered Hash Table Entry (QcstStoreCHTEntry) API to update the entry to the correct value. The possible values are:

Entry status requested. Specifies the entry status to use when returning the list of keys. The possible values are:

Format name. The content and format of the information returned for each clustered hash table key. The value must be set to CHTL0100.

Key. A key stored in the clustered hash table.

Length of key. The length of the key stored in the clustered hash table.

Length of entry information returned. The total length of the entry information returned for the key. This value is used to increment to the next key in the list.

Offset to key. The bytes from the beginning of the entry to the Key field.

Owning user profile. The user profile that owns the entry associated with this key.

Owning user profile requested. Specifies the owning user profile to use when returning the list of keys. The owning user profile is the user profile that originally stored the entry. Valid special values for this field are:

Reserved. This field will contain hexadecimal zeroes.

Storing user profile. The user profile that last stored the entry associated with this key.

Storing user profile requested.Specifies the storing user profile to use when returning the list of keys. The storing user profile is the user profile that last stored the entry. Valid special values for this field are:

User space library name. The name of the library that contains the user space.

User space name. The name of the user space that receives the list.

Error Messages