SpmiNextValue Subroutine

Purpose

Returns either the first SpmiStatVals structure in a set of statistics or the next SpmiStatVals structure in a set of statistics and a decoded value based on the type of data value extracted from the data field of an SpmiStatVals structure.

Library

SPMI Library (libSpmi.a)

Syntax

#include sys/Spmidef.h

struct SpmiStatVals*SpmiNextValue( StatSet, StatVal, value)
struct SpmiStatSet *StatSet;
struct SpmiStatVals *StatVal;
float *value;

Description

Instead of issuing subroutine calls to SpmiFirstVals Subroutine / SpmiNextVals Subroutine (to get the first or next SpmiStatVals structure) followed by calls to SpmiGetValue (to get the decoded value from the SpmiStatVals structure), the SpmiNextValue subroutine returns both in one call. This subroutine call returns a pointer to the first SpmiStatVals structure belonging to the StatSet parameter if the StatVal parameter is NULL. If the StatVal parameter is not NULL, the next SpmiStatVals structure is returned, taking the structure identified by the StatVal parameter as the current structure. The data value corresponding to the returned SpmiStatVals structure is decoded and returned in the field pointed to by the value argument. In decoding the data value, the subroutine does the following:

• 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 SpmiStatVals structure.
  • If the data value is of type SiCounter, the subroutine returns the value of the val_change field of the SpmiStatVals structure divided by the elapsed number of seconds since the previous time a data value was requested for this set of statistics.

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.

StatVal

Specifies either a NULL pointer or a pointer to a valid structure of type SpmiStatVals as created by the SpmiPathAddSetStat Subroutine call or returned by a previous SpmiNextValue subroutine call. If StatVal is NULL, then the first SpmiStatVals pointer belonging to the set of statistics pointed to by StatSet is returned.

valueA pointer used to return a decoded value based on the type of data value extracted from the data field of the returned SpmiStatVals structure.

Return Value

The SpmiNextValue subroutine returns a pointer to a SpmiStatVals structure if successful. If unsuccessful, the subroutine returns a NULL value.

If the StatVal parameter is:

NULL The first SpmiStatVals structure belonging to the StatSet parameter is returned.

not NULL The next SpmiStatVals structure after the structure identified by the StatVal parameter is returned and the value parameter is used to return a decoded value based on the type of data value extracted from the data field of the returned SpmiStatVals structure.

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.

Programming Notes

The SpmiNextValue subroutine maintains internal state information so that retrieval of the next data value from a statset can be done without traversing linked lists of data structures. The stats information is kept separate for each process, but is shared by all threads of a process.

If the subroutine is accessed from multiple threads, the state information is useless and the performance advantage is lost. The same is true if the program is simultaneously accessing two or more statsets. To benefit from the performance advantage of the SpmiNextValue subroutine, a program should retrieve all values in order from one stat set before retrieving values from the next statset.

The implementation of the subroutine allows a program to retrieve data values beginning at any point in the statset if the SpmiStatVals pointer is known. Doing so will cause a linked list traversal. If subsequent invocations of SpmiNextValue uses the value returned from the first and following invocation as their second argument, the traversal of the link list can be avoided.

It should be noted that the value returned by a successful SpmiNextValue invocation is always the pointer to the SpmiStatVals structure whose data value is decoded and returned in the value argument.

Files