SpmiGetStatSet Subroutine

Purpose

Requests the SPMI to read the data values for all statistics belonging to a specified set.

Library

SPMI Library (libSpmi.a)

Syntax

#include sys/Spmidef.h

int SpmiGetStatSet(StatSet, Force);
struct SpmiStatSet *StatSet;
boolean Force;

Description

The SpmiGetStatSet subroutine requests the SPMI to read the data values for all statistics belonging to the SpmiStatSet identified by the StatSet parameter. The Force parameter is used to force the data values to be refreshed from their source.

The Force parameter works by resetting a switch held internally in the SPMI for all SpmiStatVals and SpmiHotVals structures, regardless of the SpmiStatSets and SpmiHotSets to which they belong. Whenever the data value for a statistic is requested, this switch is checked. If the switch is set, the SPMI reads the latest data value from the original data source. If the switch is not set, the SPMI reads the data value stored for the SpmiStatVals structure. This mechanism allows a program to synchronize and minimize the number of times values are retrieved from the source. One method is to ensure the force request is not issued more than once per elapsed amount of time.

This subroutine is part of the server option of the Performance Aide for AIX® licensed product and is also included in the Performance Toolbox for AIX licensed product.

Parameters

StatSet

Specifies a pointer to a valid structure of type SpmiStatSet as created by the SpmiCreateStatSet subroutine call.

Force

If set to true, forces a refresh from the original source before the SPMI reads the data values for the set. If set to false, causes the SPMI to read the data values as they were previously retrieved from the data source.

When the force argument is set true, the effect is that of marking all statistics known by the SPMI as obsolete, which causes the SPMI to refresh all requested statistics from kernel memory or other sources. As each statistic is refreshed, the obsolete mark is reset. Statistics that are not part of the StatSet specified in the subroutine call remain marked as obsolete. Therefore, if an application repetitively issues the SpmiGetStatSet and SpmiGetHotSet subroutine calls for multiple statsets and hotsets, each time, only the first such call need set the force argument to true.

Return Values

The SpmiGetStatSet subroutine returns a value of 0 if successful. If unsuccessful, the subroutine returns a nonzero value.

Error Codes

All SPMI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:

• extern char SpmiErrmsg[];
• extern int SpmiErrno;

If the subroutine returns without an error, the SpmiErrno variable is set to 0 and the SpmiErrmsg character array is empty. If an error is detected, the SpmiErrno variable returns an error code, as defined in the sys/Spmidef.h file, and the SpmiErrmsg variable contains text, in English, explaining the cause of the error. See the List of SPMI Error Codes for more information.

Files