RSiGetHotItem Subroutine

Purpose

Locates and decodes the next SpmiHotItems element at the current position in an incoming data packet of type hot_feed.

Library

RSI Library (libSpmi.a)

Syntax

#include sys/Rsi.h

struct SpmiHotVals *RSiGetHotItem(rhandle, HotSet, index, value,
absvalue, name)
RSiHandle rhandle;
struct SpmiHotSet **HotSet;
int *index;
float *value;
flost absvalue;
char **name;

Description

The RSiGetHotItem subroutine locates the SpmiHotItems structure in the hot_feed data packet indexed by the value of the index parameter. The subroutine returns a NULL value if no further SpmiHotItems structures are found. The RSiGetHotItem subroutine should only be executed after a successful call to the RSiGetHotSet subroutine.

The RSiGetHotItem subroutine is designed to be used for walking all SpmiHotItems elements returned in a hot_feed data packet. Because the data packet may contain elements belonging to more than one SpmiHotSet, the index is purely abstract and is only used to keep position. By feeding the updated integer pointed to by index back to the next call, the walking of the hot_feed packet can be done in a tight loop. Successful calls to RSiGetHotItem 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 Performance Toolbox for AIX® licensed product.

Parameters

rhandle

Must point to a valid RSiHandle handle, which was previously initialized by the RSiOpen (RSiOpen Subroutine) subroutine.

HotSet

Used to return a pointer to a valid SpmiHotSet structure as obtained by a previous RSiCreateHotSet (RSiCreateHotSet Subroutine) subroutine call. The calling program can use this value to locate the SpmiHotSet if its address was stored by the program after it was created. The time stamps in the SpmiHotSet are updated with the time stamps of the decoded SpmiHotItems element.

index

A pointer to an integer that contains the desired relative element number in the SpmiHotItems array across all SpmiStatVals contained in the data packet. A value of zero points to the first element. When the RSiGetHotItem subroutine returns, the integer contain the index of the next SpmiHotItems element in the data packet. By passing the returned index parameter to the next call to RSiGetHotItem, the calling program can iterate through all SpmiHotItems elements in the hot_feed data packet.

value

A pointer to a float variable. A successful call will return the decoded data value of the peer statistic. Before the value is returned, the RSiGetHotItem 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.

absvalue

A pointer to a float variable. A successful call will return the decoded value of the val field of the SpmiHotItems structure of the peer statistic. In case of a statistic of type SiQuantity, this value will be the same as the one returned in the argument value. In case of a peer statistic of type SiCounter, the value returned is the absolute value of the counter.

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 RSiGetHotItem subroutine returns a pointer to the current SpmiHotVals structure within the hotset. If no more SpmiHotItems elements 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. In the returned SpmiHotVals structure, all fields contain the correct values as declared, except for the following:

stat

Declared as SpmiStatHdl, actually points to a valid SpmiStat structure. By casting the handle to a pointer to SpmiStat, data in the structure can be accessed.

grandpa

Contains the cx_handle for the parent context of the peer contexts.

items

When using the Spmi interface this is an array of SpmiHotItems structures. When using the RSiGetHotItem subroutine, the array is empty and attempts to access it will likely result in segmentation faults or access of not valid data.

path

Will contain the path to the parent of the peer contexts. Even when the peer contexts are multiple levels below the parent context, the path points to the top context because the peer context identifiers in the SpmiHotItems elements will contain the path name from there and on. For example, if the hotvals peer set defines all volume groups, the path specified in the returned SpmiHotVals structure would be “FS” and the path name in one SpmiHotItems element may be “rootvg/lv01”. When combined with the metric name from the stat field, the full path name can be constructed as, for example, “FS/rootvg/lv01/%totfree”.

Error Codes

All Remote Statistic Interface (RSI) subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:

• extern char RSiEMsg[];
• extern int RSiErrno;

If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType.

Files