Adds a set of peer statistics values to a hotset.
SPMI Library (libSpmi.a)
#include sys/Spmidef.h
struct SpmiHotVals *SpmiAddSetHot(HotSet, StatName, GrandParent, maxresp, threshold, frequency, feed_type, except_type, severity, trap_no) struct SpmiHotSet *HotSet; char *StatName; SpmiCxHdl GrandParent; int maxresp; int threshold; int frequency; int feed_type; int excp_type; int severity; int trap_no;
The SpmiAddSetHot subroutine adds a set of peer statistics to a hotset. The SpmiHotSet structure that provides the anchor point to the set must exist before the SpmiAddSetHot subroutine call can succeed.
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.
Specifies a pointer to a valid structure of type SpmiHotSet as created by the SpmiCreateHotSet (SpmiCreateHotSet) subroutine call.
Specifies the name of the statistic within the subcontexts (peer contexts) of the context identified by the GrandParent parameter.
Specifies a valid SpmiCxHdl handle as obtained by another subroutine call. The handle must identify a context with at least one subcontext, which contains the statistic identified by the StatName parameter. If the context specified is one of the RTime contexts, no subcontext need to exist at the time the SpmiAddSetHot subroutine call is issued; the presence of the metric identified by the StatName parameter is checked against the context class description.
If the context specified has or may have multiple levels of instantiable context below it (such as the FS and RTime/ARM contexts), the metric is only searched for at the lowest context level. The SpmiHotSet created is a pseudo hotvals structure used to link together a peer group of SpmiHotValsstructures, which are created under the covers, one for each subcontext of the GrandParent context. In the case of RTime/ARM, if additional contexts are later added under the GrandParent contexts, additional hotsets are added to the peer group. This is transparent to the application program, except that the SpmiFirstHot, SpmiNextHot, and SpmiNextHotItem subroutine calls will return the peer group SpmiHotVals pointer rather than the pointer to the pseudo structure.
Note that specifying a specific volume group context (such as FS/rootvg) or a specific application context (such as RTime/ARN/armpeek) is still valid and won't involve creation of pseudo SpmiHotVals structures.
Must be non-zero if excp_type specifies that exceptions or SNMP traps must be generated. If specified as zero, indicates that all SPMIHotItems that meet the criteria specified by threshold must be returned, up-to a maximum of maxresp items. If both exceptions/traps and feeds are requested, the maxresp value is used to cap the number of exceptions/alerts as well as the number of items returned. If feed_type is specified as SiHotAlways, the maxresp parameter is still used to return at most maxresp items.
Where the GrandParent argument specifies a context that has multiple levels of instantiable contexts below it, the maxresp is applied to each of the lowest level contexts above the the actual peer contexts at a time. For example, if the GrandParent context is FS (file systems) and the system has three volume groups, then a maxresp value of 2 could cause up to a maximum of 2 x 3 = 6 responses to be generated.
Must be non-zero if excp_type specifies that exceptions or SNMP traps must be generated. If specified as zero, indicates that all values read qualify to be returned in feeds. The value specified is compared to the data value read for each peer statistic. If the data value exceeds the threshold, it qualifies to be returned as an SpmiHotItems element in the SpmiHotVals structure. If the threshold is specified as a negative value, the value qualifies if it is lower than the numeric value of threshold. If feed_type is specified as SiHotAlways, the threshold value is ignored for feeds. For peer statistics of type SiCounter, the threshold must be specified as a rate per second; for SiQuantity statistics the threshold is specified as a level.
Must be non-zero if excp_type specifies that exceptions or SNMP traps must be generated. Ignored for feeds. Specifies the minimum number of minutes that must expire between any two exceptions/traps generated from this SpmiHotVals structure. This value must be specified as no less than 5 minutes.
Specifies if feeds of SpmiHotItems should be returned for this SpmiHotVals structure. The following values are valid:
Controls the generation of exception data packets and/or the generation of SNMP Traps from xmservd. Note that these types of packets and traps can only actually be sent if xmservd is running. Because of this, exception packets and SNMP traps are only generated as long as xmservd is active. Traps can only be generated on AIX systems. The conditions for generating exceptions and traps are controlled by the threshold and frequency parameters. The following values are valid for excp_type:
Required to be positive and greater than zero if exceptions are generated, otherwise specify as zero. Used to assign a severity code to the exception for display by exmon.
Required to be positive and greater than zero if SNMP traps are generated, otherwise specify as zero. Used to assign the trap number in the generated SNMP trap.
The SpmiAddSetHot subroutine returns a pointer to a structure of type SpmiHotVals if successful. If unsuccessful, the subroutine returns a NULL value.
The SpmiAddSetHot functions in a straight forward manner and as described previously in all cases where the GrandParent context is a context that has only one level of instantiable contexts below it. This covers most context types such as CPU, Disk, LAN, etc. In a few cases, currently only the FS (file system) and RTime/ARM (application response) contexts, the SPMI works by creating pseudo-hotvals structures that effectively expand the hotset. These pseudo-hotvals structures are created either at the time the SpmiAddSetHot call is issued or when new subcontexts are created for a context that's already the GrandParent of a hotvals peer set. For example:
When a peer set is created for RTime/ARM, maybe only a few or no subcontexts of this context exists. If two applications were defined at this point, say checking and savings, one valsset would be created for the RTime/ARM context and a pseudo-valsset for each of RTime/ARM/checking and RTime/ARM/savings. As new applications are added to the RTime/ARM contexts, new pseudo-valssets are automatically added to the hotset.
Pseudo-valssets represent an implementation convenience and also helps minimize the impact of retrieving and presenting data for hotsets. As far as the caller of the RSiGetHotItem subroutine call is concerned, it is completely transparent. All this caller will ever see is the real hotvals structure. That is not the case for callers of SpmiFirstHot, SpmiNextHot, and SpmiNextHotItem. All of these subroutines will return pseudo-valssets and the calling program should be prepared to handle this.
All SPMI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
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.
| /usr/include/sys/Spmidef.h | Declares the subroutines, data structures, handles, and macros that an application program can use to access the SPMI. |