RSiAddSetHot Subroutine

Purpose

Add a single set of peer statistics to an already defined SpmiHotSet.

Library

RSI Library (libSpmi.a)

Syntax

#include sys/Rsi.h

struct SpmiHotVals *RSiAddSetHot(rhandle, HotSet, StatName,
GrandParent,
                                 maxresp, threshold, frequency, feed_type,
                                 except_type, severity, trap_no)
RSiHandle rhandle;
struct SpmiHotSet *HotSet;
char *StatName;
cx_handle GrandParent;
int maxresp;
int threshold;
int frequency;
int feed_type;
int excp_type;
int severity;
int trap_no;

Parameters

rhandle

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

HotSet

Specifies a pointer to a valid structure of type SpmiHotSet as created by the RSiCreateHotSet (RSiCreateHotSet Subroutine) subroutine call.

StatName

Specifies the name of the statistic within the subcontexts (peer contexts) of the context identified by the GrandParent parameter.

GrandParent

Specifies a valid cx_handle 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 be created 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 SpmiHotVals structures, 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 RSiGetHotItem (RSiGetHotItem Subroutine) subroutine call 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.

maxresp

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.

threshold

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.

frequency

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.

feed_type

Specifies if feeds of SpmiHotItems should be returned for this SpmiHotVals structure. The following values are valid:

SiHotNoFeed No feeds should be generated

SiHotThreshold Feeds are controlled by threshold.

SiHotAlways All values, up-to a maximum of maxresp must be returned as feeds.

excp_type

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®. The conditions for generating exceptions and traps are controlled by the threshold and frequency parameters. The following values are valid for excp_type:

SiNoHotException Generate neither exceptions not traps.

SiHotException Generate exceptions but not traps.

SiHotTrap Generate SNMP traps but not exceptions.

SiHotBoth Generate both exceptions and SNMP traps.

severity

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.

trap_no

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.

This subroutine is part of the Performance Toolbox for AIX licensed product.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiHotVals. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg. If you attempt to add more values to a statset than the current local buffer size allows, RSiErrno is set to RSiTooMany. If you attempt to add more values than the buffer size of the remote host's xmservd daemon allows, RSiErrno is set to RSiBadStat and the status field in the returned packet is set to too_many_values.

The external integer RSiMaxValues holds the maximum number of values acceptable with the data-consumer's buffer size.

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