List Cluster Information (QcstListClusterInfo) API

The List Cluster Information (QcstListClusterInfo) API is used to retrieve information about a cluster. It must be called from a program running on one of the nodes in the cluster. The information returned may not be current if this API is called from a program running on a node that has a status of Inactive or Failed. This API may be called from a cluster resource group exit program.

Authorities and Locks

User Space Authority

*CHANGE

User Space Library Authority

*EXECUTE

User Queue Lock

*EXCLRD

Required Parameter Group

Qualified user space name

OUTPUT; CHAR(20)

The user space that receives the information and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name. No special values (QTEMP, *CURLIB, or *LIBL) can used for the library name.

Cluster name

INPUT; CHAR(10)

The name of the cluster for which information is retrieved.

Format name

INPUT; CHAR(8)

The format of the information to be returned. Supported format names are:

LCTI0100	Returns information about a specific node or all nodes in the cluster and additional information about the cluster.
LCTI0101	Returns information about a specific node or all nodes in the cluster and additional information about the cluster with IPv6 support.
LCTI0200	Returns information about the cluster monitors for a specific node or the cluster monitors for all nodes. This format can only be used with a cluster at cluster version 7 or greater.

Node ID

INPUT; CHAR(8)

A valid simple name that uniquely identifies a node. *ALL special value can be used to return information about all nodes in the cluster. The *ALL special value must be left-justified.

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 Generated Lists

The cluster information list consists of:

• A user space
• A generic header
• A header section
• An input parameter section
• A list data section
  • LCTI0100 or
  • LCTI0101 or
  • LCTI0200

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

When you retrieve list entry information from a user space, you must not use the entry size returned in the generic header. Each entry may have a different size. The size of each entry may be padded at the end.

Input Parameter Section

Header Section

Global information about the cluster.

LCTI0100 Format

Offset		Type	Field
Dec	Hex
These fields are repeated for each node entry returned.		Array(*) of CHAR(*)	Node entry array
		BINARY(4)	Length of node entry
		CHAR(8)	Node ID
		BINARY(4)	Node status
		BINARY(4)	Offset to cluster interface array
		BINARY(4)	Number of cluster interface array entries
		BINARY(4)	Potential node version
		BINARY(4)	Potential node version modification level
		CHAR(10)	Device domain name
		Array(*) of CHAR(16)	Cluster interface array
These fields are repeated for each cluster interface entry returned.		CHAR(16)	Cluster interface address - IPv4

LCTI0101 Format

LCTI0200 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Number of cluster monitor entries
4	4	BINARY(4)	Offset to cluster monitor array
8	8	Array(*) of CHAR(*)	Cluster monitor array
These fields are repeated for each monitor entry returned.
		BINARY(4)	Length of cluster monitor entry
		BINARY(4)	Cluster monitor entry type
		CHAR(8)	Node ID where cluster monitor runs
		CHAR(*)	Type specific data

Type specific data for CIM and Representational State Transfer (REST) cluster monitor entries

Field Descriptions

Cluster interface address - IPv4. The cluster interface address is an IP address which is used by Cluster Resource Services to communicate with other nodes in the cluster. Each IPv4 address is returned as a null-terminated string and represented in dotted decimal format. If the cluster interface address is not actually an IPv4 address, the special value *IPV6 padded on the right with hex zeros is returned.

Cluster interface address - IPv4 or IPv6. The cluster interface address is an IP address which is used by Cluster Resource Services to communicate with other nodes in the cluster. Either an IPv4 or IPv6 address is supported. When Cluster interface address type field is 0, the returned address is an IPv4 address in dotted decimal format and padded on the right with hex zeros. When Cluster interface address type field is 1, the returned address is an IPv6 address and padded on the right with hex zeros. The coded character set identifier (CCSID) of the IP address returned will match the CCSID of the job calling the API.

Cluster interface entry array. Array of cluster interface addresses in use by each node in the node entry array.

Cluster interface address type. Type of IP address that follows in the Cluster interface address - IPv4 or IPv6 field. The possible values are:

0	Cluster interface address is IPv4.
1	Cluster interface address is IPv6.

Cluster message queue library name. The name of the library that contains the message queue to receive cluster messages. This field will contain hexadecimal zeroes if no cluster message queue is specified.

Cluster message queue name. The name of the message queue to receive messages relating to cluster or node level events. For cluster version 6, messages relating to failover will be sent to this queue. This field will contain *NONE left justified and padded with blanks if no cluster message queue is specified.

Cluster monitor array. Array of cluster monitors which have been configured with the Add Cluster Monitor (QcstAddCluster Monitor) API.

Cluster monitor entry type. The type of cluster monitor entry.

1	CIM server monitor.
2	Representational State Transfer (REST) server monitor.

Cluster name. The name of the cluster for which information is retrieved.

Current cluster version. The version at which the nodes in the cluster are actively communicating with each other. This value in conjunction with the potential node version determines what nodes can join in the cluster. This value also determines the cluster's ability to use new functions supported by the node's potential node version. It is set when the cluster is created and can be changed by the Adjust Cluster Version (QcstAdjustClusterVersion) API.

Current cluster version modification level. The modification level of the current cluster version. The modification level further identifies the version at which the nodes in the cluster communicate. It is updated when code changes that impact the version are applied to the system.

Device domain name. The name of the device domain that this node belongs to. This field will contain hexadecimal zeros if the node does not belong to a device domain.

Failover default action. Indicates what clustering should do when a response to the failover message on the cluster message queue was not received in the failover wait time limit. Valid values are:

Failover wait time. Number of minutes to wait for a reply to the failover message that was enqueued on the cluster message queue. Valid values are:

Format name. The content and format of the information returned in the user space.

Information status. Indicates the consistency of the retrieved information.

Length of cluster interface array entry. The length of an entry in the cluster interface array. This length should be used to navigate to the next cluster interface array entry.

Length of cluster monitor entry. The length of the cluster monitor entry.

Length of node entry. The length of the node entry, including the cluster interface array.

Node entry array. Array of cluster nodes for which information is being returned.

Node ID. A valid simple name that uniquely identifies a node.

Node ID where cluster monitor runs. The ID of the node where a cluster monitor runs and receives information from a server.

Node status. The status of the node in the cluster. See Cluster Node Status for the possible values and definitions of the status.

Number of cluster interface array entries. The number of IP interfaces used by the node for Cluster Resource Services.

Number of cluster monitor entries. The number of entries in the cluster monitor array. This can be zero if no monitors have been added to the cluster or no monitors have been added to the particular node whose information is being retrieved.

Offset to cluster interface array. The offset from the beginning of the node entry to the first entry in the cluster interface array.

Offset to cluster monitor array. The offset from the beginning of the user space to the first cluster monitor entry.

Potential node version. The version at which the node is capable of communicating with the other nodes in the cluster. This is the value associated with the cluster code installed on the node. It will be used to determine if the node can join a cluster. If communications have not yet been established with the node (status of New), then the potential node version will be reported as 0.

Potential node version modification level.The modification level of the potential node version. The modification level further identifies the version at which the node is capable of communicating with the other nodes in the cluster. It is updated when code changes that impact the version are applied to the system.

Reserved. The field will contain hexadecimal zeroes.

Server host name.The name of the server host being used to monitor the status of one or more cluster nodes. This is a null terminated character string. The data is returned in the job's default CCSID.

Server user ID.The user id on the server host used by Cluster Resource Services for authentication when information is requested from the server. This is a null terminated character string. The data is returned in the job's default CCSID.

User space name. The name of the user space.

User space library name. The name of the library in which the user space resides. No special values are supported for library name.

Error Messages

Messages that are delivered through the error code parameter are listed here.

Message ID	Error Message Text
CPF2113 E	Cannot allocate library &1.
CPF3C1E E	Required parameter &1 omitted.
CPF3C21 E	Format name &1 is not valid.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF9801 E	Object &2 in library &3 not found.
CPF9802 E	Not authorized to object &2 in &3.
CPF9803 E	Cannot allocate object &2 in library &3.
CPF9804 E	Object &2 in library &3 damaged.
CPF9810 E	Library &1 not found.
CPF9820 E	Not authorized to use library &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFBB02 E	Cluster &1 does not exist.
CPFBB09 E	Cluster node &1 does not exist in cluster &2.
CPFBB38 E	Library name &1 not allowed for this request.
CPFBB70 E	Request &1 not compatible with current cluster version.

[ Back to top | Cluster APIs | APIs by category ]