perfstat_ssp_ext Subroutine

Edit online

Purpose

Retrieves the tier, failure group, physical volume, and node data that are associated with shared storage pool (SSP).

Syntax

#include <libperfstat.h>

int perfstat_ssp_ext (name, userbuff, sizeof_struct, desired_number, ssp_flag)
perfstat_ssp_id_t * name;
perfstat_ssp_t * userbuff;
size_t sizeof_struct;
int desired_number;
ssp_flag_t ssp_flag;

Description

The perfstat_ssp_ext subroutine retrieves the SSP statistics on the tier, failure group, and the physical volumes that belong to the failure group. This subroutine also retrieves nodes data that belong to the SSP.

To retrieve the number of tiers in the SSP, you must set the name and userbuff parameters to NULL, the desired_number parameter to 0, and the ssp_flag parameter to SSPTIER.

To retrieve the number of available failure groups in the SSP, you must set the name and userbuff parameters to NULL, the desired_number parameter to 0, and the ssp_flag parameter to SSPFG.

To retrieve the number of physical volumes that are associated with the SSP, you must set the name and userbuff parameters to NULL, the desired_number parameter to 0, and the ssp_flag parameter to SSPPV.

To retrieve the number of nodes that are associated with the SSP, you must set the name and userbuff parameters to NULL, the desired_number parameter to 0, and the ssp_flag parameter to SSPNODE.

To retrieve data that is specific to a tier, failure group, physical volume, or node, you must specify the name parameter.

To enable collection of these data, you must configure the cluster statistics collection by running the following subroutine: 
perfstat_config(PERFSTAT_ENABLE | PERFSTAT_CLUSTER_STATS, NULL)
After the SSP data collection is complete, you must disable the cluster statistics collection by running the following subroutine:
perfstat_config(PERFSTAT_DISABLE | PERFSTAT_CLUSTER_STATS, NULL)
Note: The perfstat_ssp_ext subroutine can function only on Virtual I/O Server (VIOS).

Parameters

name
Filter for retrieving the tier, failure group, and physical volumes in a shared storage pool. The following filters are possible:
name->tier.name
Specifies the tier name for which data must be returned.
name->tier.id
Specifies the tier ID for which data must be returned.
name.fg.name
Specifies the failure group name for which data must be returned.
name->fg.id
Specifies the failure group ID for which data must be returned.
name->pv.name
Specifies the physical volume name for which data must be returned.
name->pv.id
Specifies the physical volume ID for which data must be returned.
name->name
Specifies the node name for which the data must be returned.
name->spec
Specifies the filter. The following values can be specified for this attribute:
PERFFILT_ID
Specifies that the filters are based on ID of a tier, failure group, or physical volume.
PERFFILT_NAME
Specifies that the filters are based on name of a tier, failure group, physical volume, or node.
Note: Both ID and name cannot be used at the same time.
PERFFILT_TIER
Specifies that the filters are specific to a tier. The filter can be based on tier ID or tier name. The spec attribute must be set accordingly.
PERFFILT_FG
Specifies that the filters are specific to a failure group. The filter can be based on failure group ID or failure group name. The spec attribute must be set accordingly.
PERFFILT_PV
Specifies that the filters are specific to a physical volume. The filter can be based on unique disk identifier (UDID) or physical volume name. The spec attribute must be set in both the cases.
PERFFILT_NODE
Specifies that the filters are specific to a node.
Note: Either the PERFFILT_ID or PERFFILT_NAME attribute values must be specified.
userbuff
Points to the memory area that is filled with the perfstat_ssp_t structure. Memory is allocated to this parameter with the calculation of (sizeof (perfstat_ssp_t) * returned_count), where returned_count is the value obtained by setting this parameter to NULL and the desired_number parameter to zero.
sizeof_struct
Specifies the size of the perfstat_ssp_t structure.
desired_number
Specifies the number of the perfstat_ssp_t structures to copy to the userbuff parameter.
ssp_flag
Specifies whether tier, failure group, or physical volume needs to be retrieved. You must set this parameter to one of the following values:
SSPTIER
When the SSPTIER flag is invoked, the userbuff parameter is set to NULL, and the desired_number parameter is set to 0, the number of tiers based on the name parameter in the SSP is returned. When the userbuff parameter is allocated, tier-specific data is populated into the user buffer. The name->spec parameter can be used with the following specifications:
  • PERFFILT_ID or PERFFILT_NAME
  • PERFFILT_TIER
SSPFG
When the SSPFG flag is invoked, the userbuff parameter is set to NULL, and the desired_number parameter is set to 0, the number of failure groups based on the name parameter in the SSP is returned. When the userbuff parameter is allocated, the failure group-specific data is populated into the user buffer based on the name parameter. The name.spec flag can be used with the following specifications for the filter:
  • PERFFILT_ID or PERFFILT_NAME
  • PERFFILT_TIER
  • PERFFILT_FG
SSPPV
When the SSPPV flag is invoked, the userbuff parameter is set to NULL, and the desired_number parameter is set to 0, the number of physical volumes based on the name parameter in the SSP is returned. When the userbuff parameter is allocated, the tier-specific data is populated into the user buffer. The name.spec flag can be used with the following specifications for the filter:
  • PERFFILT_ID or PERFFILT_NAME
  • PERFFILT_TIER
  • PERFFILT_FG
  • PERFFILT_PV
SSPNODE
When the SSPNODE flag is invoked, the userbuff parameter is set to NULL, and the desired_number parameter is set o 0, the number of nodes based on the name parameter in the SSP is returned. When the userbuff parameter is allocated, the node-specific data is populated into the user buffer. The name.spec flag can be used with the following specifications for the filter:
  • PERFFILT_NAME
  • PERFFILT_NODE

Return values

On successful completion of the subroutine, the number of filled structures is returned. If the subroutine is unsuccessful, a value of -1 is returned and the errno variable indicates the error.

Error codes

The perfstat_ssp_ext subroutine fails because of one of the following errors:

EINVAL
One of the parameters is not valid.
EFAULT
The memory is not sufficient.
ENOMEM
The default length of the string is short.
ENOMSG
The dictionary is not accessible.
ETIMEDOUT
The connection timed out.
ENOENT
Data specified by the filter is not found.

Files

The libperfstat.h file defines standard macros, data types, and subroutines.