SpmiNextHotItem Subroutine

Purpose

Locates and decodes the next SpmiHotItems element at the current position in an SpmiHotSet.

Library

SPMI Library (libSpmi.a)

Syntax

#include sys/Spmidef.h

struct SpmiHotVals *SpmiNextHotItem(HotSet, HotVals, index,
value, name)
struct SpmiHotSet *HotSet;
struct SpmiHotVals *HotVals;
int *index;
float *value;
char **name;

Description

The SpmiNextHotItem subroutine locates the next SpmiHotItems structure belonging to an SpmiHotSet, taking the element identified by the HotVals and index parameters as the current one. The subroutine returns a NULL value if no further SpmiHotItems structures are found. The SpmiNextHotItem subroutine should only be executed after a successful call to the SpmiGetHotSet subroutine.

The SpmiNextHotItem subroutine is designed to be used for walking all SpmiHotItems elements returned by a call to the SpmiGetHotSet subroutine, visiting the SpmiHotVals structures one by one. By feeding the returned value and the updated integer pointed to by index back to the next call, this can be done in a tight loop. Successful calls to SpmiNextHotItem will decode each SpmiHotItems element and return the data value in value and the name of the peer context that owns the corresponding statistic in name.

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 valid pointer to an SpmiHotSet structure as obtained by a previous SpmiCreateHotSet call.

HotVals

Specifies a pointer to an SpmiHotVals structure as returned by a previousSpmiNextHotItem, SpmiFirstHot, or SpmiNextHot subroutine call or as returned by an SpmiAddSetHot subroutine call. If this parameter is specified as NULL, the first SpmiHotVals structure of the SpmiHotSet is used and the index parameter is assumed to be set to zero, regardless of its actual value.

index

A pointer to an integer that contains the desired element number in the SpmiHotItems array of the SpmiHotVals structure specified by HotVals. A value of zero points to the first element. When the SpmiNextHotItem subroutine returns, the integer contain the index of the next SpmiHotItems element within the returned SpmiHotVals structure. If the last element of the array is decoded, the value in the integer will point beyond the end of the array, and the SpmiHotVals pointer returned will point to the peer set, which has now been completely decoded. By passing the returned SpmiHotVals pointer and the index parameter to the next call to SpmiNextHotItem, the subroutine will detect this and proceed to the first SpmiHotItems element of the next SpmiHotVals structure if one exists.

value

A pointer to a float variable. A successful call will return the decoded data value for the statistic. Before the value is returned, the SpmiNextHotItem function:

• Determines the format of the data field as being either SiFloat or SiLong and extracts the data value for further processing.
• Determines the data value as being either type SiQuantity or type SiCounter and performs one of the actions listed here:
  • If the data value is of type SiQuantity, the subroutine returns the val field of the SpmiHotItems structure.
  • If the data value is of type SiCounter, the subroutine returns the value of the val_change field of the SpmiHotItems structure divided by the elapsed number of seconds since the previous time a data value was requested for this set of statistics.

name

A pointer to a character pointer. A successful call will return a pointer to the name of the peer context for which the data value was read.

Return Values

The SpmiNextHotItem subroutine returns a pointer to the current SpmiHotVals structure within the hotset. If no more SpmiHotVals structures are available, the subroutine returns a NULL value. The structure returned contains the data, such as threshold, which may be relevant for presentation of the results of an SpmiGetHotSet subroutine call to end-users. A returned pointer may refer to a pseudo-hotvals structure as described in the SpmiAddSetHot subroutine.

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