SpmiGetHotSet Subroutine

Purpose

Requests the SPMI to read the data values for all sets of peer statistics belonging to a specified SpmiHotSet.

Library

SPMI Library (libSpmi.a)

Syntax

#include sys/Spmidef.h

int SpmiGetHotSet(HotSet, Force);
struct SpmiHotSet *HotSet;
boolean Force;

Description

The SpmiGetHotSet subroutine requests the SPMI to read the data values for all peer sets of statistics belonging to the SpmiHotSet identified by the HotSet 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 peer 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 in the SpmiHotVals structure. This mechanism allows a program to synchronize and minimize the number of times values are retrieved from the source. One method programs can use 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

HotSet

Specifies a pointer to a valid structure of type SpmiHotSet as created by the SpmiCreateHotSet 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 HotSet specified in the subroutine call remain marked as obsolete. Therefore, if an application repetitively issues a series of, SpmiGetHotSet and SpmiGetStatSet subroutine calls for multiple hotsets and statsets, each time, only the first such call need set the force argument to true.

Return Values

The SpmiGetHotSet 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