[ Previous | Next | Contents | Glossary | Search ]
Performance Toolbox Version 1.2 and 2 for AIX: Guide and Reference

Chapter 17. Remote Statistics Interface Programming Guide

This chapter provides information about the Remote Statistics Interface.

Remote Statistics Interface API Overview

An application programming interface (API) is available for those who want to develop programs that access the statistics available from one or more xmservd daemons. The API is called the Remote Statistics Interface or the RSI Interface. This chapter describes how you use the RSI Interface API by walking you through a couple of sample programs. Those sample programs, and others, are provided in machine-readable form as well. The sample programs can be found in the directory:

/usr/samples/perfmgr

You use the RSI Interface API to write programs that access one or more xmservd daemons. This allows you to develop programs that print, post-process, or otherwise manipulate the raw statistics provided by the xmservd daemon(s). Such programs are known as Data-Consumer programs.

Makefiles

The include files are based upon a number of define directives being properly set. They are normally defined with the -D preprocessor flag. The following define directives should be in effect for compiling on AIX Version 3.2 and AIX Version 4.

A Makefile to build all the sample programs provided could look like the one shown in the listing below:

LIBS = -L./ -lbsd -lSpmi
CC = cc
CFLAGS = -D_BSD -D_AIX

all:: RsiCons RsiCons1 chmon

RsiCons: RsiCons.c
      $(CC) -o RsiCons RsiCons.c $(CFLAGS) $(LIBS)

RsiCons1: RsiCons1.c
      $(CC) -o RsiCons1 RsiCons1.c $(CFLAGS) $(LIBS)

chmon: chmon.c $
      $(CC) -o chmon chmon.c $(CFLAGS) $(LIBS) -lcurses

If the system you compile on doesn't support ANSI function prototypes. add the following flag:

-D_NO_PROTO

Remote Statistics Interface List of Subroutines

As interesting and useful as it may be to watch the graphics display of statistics shown by xmperf, many other uses of the wealth of statistics are available through the xmservd daemons on all the hosts in a network. The Remote Statistics Interface API allows you to create data-consumer programs that can get full access to the statistics of any host's xmservd daemon.

The RSI interface consists of several groups of subroutines as follows:

Initialization and Termination

RSiInit Allocates or changes the table of RSI handles.
RSiOpen Initializes the RSI interface for a remote host.
RSiClose Terminates the RSI interface for a remote host and releases all memory allocated.
RSiInvite Invites data suppliers on the network to identify themselves and returns a table of data-supplier host names.

Instantiation and Traversal of Context Hierarchy

RSiInstantiate Creates (instantiates) all subcontexts of a context object.
RSiPathGetCx Searches the context hierarchy for a context that matches a context path name.
RSiFirstCx Returns the first subcontext of a context.
RSiNextCx Returns the next subcontext of a context.
RSiFirstStat Returns the first statistic of a context.
RSiNextStat Returns the next statistic of a context.

Defining Sets of Statistics to Receive

RSiAddSetHot Adds a single set of peer statistics to a hotset.
RSiCreateHotSet Creates an empty hotset.
RSiCreateStatSet Creates an empty statset.
RSiPathAddSetStat Adds a single statistic to a statset.
RSiDelSetHot Deletes a single set of peer statistics from a hotset.
RSiDelSetStat Deletes a single statistic from a statset.
RSiStatGetPath Finds the full path name of a statistic identified by an SpmiStatVals pointer.

Starting, Changing and Stopping Data Feeding

RSiStartFeed Tells xmservd to start sending data feeds for a statset.
RSiStartHotFeed Tells xmservd to start sending hot feeds for a hotset.
RSiChangeFeed Tells xmservd to change the time interval between sending data feeds for a statset.
RSiChangeHotFeed Tells xmservd to change the time interval between sending hot feeds for a hotset.
RSiStopFeed Tells xmservd to stop sending data feeds for a statset.
RSiStopHotFeed Tells xmservd to stop sending hot feeds for a hotset.

Receiving and Decoding Data Feed Packets

RSiGetHotItem Returns the peer context name and data value for the first (next) SpmiHotItems element by extraction from data feed packet.
RSiMainLoop Allows an application to suspend execution and wait to get waked up when data feeds arrive.
RSiGetValue Returns data value for a given SpmiStatVals pointer by extraction from data feed packet.
RSiGetRawValue Returns a pointer to a valid SpmiStatVals structure for a given SpmiStatVals pointer by extraction from data feed packet.

RSI Interface Concepts and Terms

Before you start using the RSI interface API you need to be aware of the format and use of the RSI interface data structures. This section explains the structures and also introduces you to the commonalities of the library functions and to some important design concepts. This section has the following subsections:

RSI Interface Data Structures

The RSI interface is based upon control blocks (data structures) that describe the current view of the statistics on a remote host and the state of the interaction between a data consumer program and the remote host's xmservd daemon. Data structures to know about are:

RSI handle
An RSI handle is a pointer to a data structure of type RSiHandleStruct. Prior to using any other RSI call, a data-consumer program must use the RSiInit subroutine to allocate a table of RSI handles. An RSI handle from the table is initialized when you open the logical connection to a host and that RSI handle must be specified as an argument on all subsequent subroutines to the same host. Only one of the internal fields of the RSI handle should be used by the data-consumer program, namely the pointer to received network packets, pi. Only in very special cases will you ever need to use this pointer, which is initialized by RSiOpen and must never be modified by a data-consumer program. If your program changes any field in the RSI handle structure, results are highly unpredictable. The RSI handle is defined in /usr/include/sys/Rsi.h .

SpmiStatVals
A single data value is represented by a structure defined in /usr/include/sys/Spmidef.h as struct SpmiStatVals. You should be aware that none of the fields defined in the structure must be modified by application programs. The two handles in the structure are symbolic references to contexts and statistics and should not be confused with pointers. The last three fields are updated whenever a data_feed packet is received. These fields are:

val
The latest actual contents of the statistics data field.
val_change
The difference (delta value) between the latest actual contents of the statistics data field and the previous value observed.
error
An error code as defined by the enum Error in include file /usr/include/sys/Spmidef.h .

Note that the two value fields are defined as union Value, which means that the actual data fields may be long or float, depending on flags in the corresponding SpmiStat structure. The SpmiStat structure can not be accessed directly from the StatVals structure (the pointer is invalid, as already mentioned). Therefore, to determine the type of data in the val and val_change fields, you must have saved the SpmiStat structure as returned by the RSiPathAddSetStat subroutine. This is rather clumsy so the subroutine RSiGetValue does everything for you and you needn't worry about keeping track of SpmiStat structures.

SpmiStat
This is a data structure to describe a statistic. It is defined in /usr/include/sys/Spmidef.h as type struct SpmiStat. If you ever need information from this data structure (apart from information that can be returned by the subroutine RSiStatGetPath ) be sure to save it as it is returned by the RSiPathAddSetStat subroutine.

The RSiGetRawValue subroutine provides another way of getting access to an SpmiStat structure but can only do so while a data feed packet is being processed.

SpmiStatSet
The xmservd daemon accepts the definition of sets of statistics that are to be extracted simultaneously and sent to the data-consumer program in a single data packet. The structure that describes such a set of statistics is defined in /usr/include/sys/Spmidef.h as of type struct SpmiStatSet. As returned by the RSiCreateStatSet subroutine, the SpmiStatSet pointer should be treated as a handle whose only purpose is to identify the correct set of statistics to several other subroutines.

When returned in a data feed packet, the SpmiStatSet structure holds the actual time the data feed packet was created (according to the remote host's clock) and the elapsed time since the latest previous data feed packet for the same SpmiStatSet was created.

SpmiHotSet
Represents another set of access structures that allow an application program to define an alternative way of extracting and processing metrics. They are used to extract data values for the most or least active statistics for a group of peer contexts. For example, it can be used to define that the program wants to receive information about the two highest loaded disks, optionally subject to the load exceeding a specified threshold.

When the SPMI receives a read request for an SpmiHotSet, the SPMI reads the latest value for all the peer sets of statistics in the hotset in one operation. This action reduces the system overhead caused by access of kernel structures and other system areas, and ensures that all data values for the peer sets of statistics within a hotset are read at the same time. The hotset may consist of one or many sets of peer statistics.

SpmiHotVals
One SpmiHotVals structure is created for each set of peer statistics selected for the hotset. When the SPMI executes a request from the application program to read the data values for a hotset, all SpmiHotVals structures in the set are updated. The RSi application program can then traverse the list of SpmiHotVals structures by using the RSiGetHotItem subroutine call.

The SpmiHotVals structure carries the data values from the SPMI to the application program. Its data carrying fields are:

error
Returns a zero value if the SPMI's last attempt to read the data values for a set of peer statistics was successful. Otherwise, this field contains an error code as defined in the sys/Spmidef.h file.
avail_resp
Used to return the number of peer statistic data values that meet the selection criteria (threshold). The field max_responses determines the maximum number of entries actually returned.
count
Contains the number of elements returned in the array items. This number will be the number of data values that met the selection criteria (threshold), capped at max_responses.
items
The array used to return count elements. This array is defined in the SpmiHotItems data structure. Each element in the SpmiHotItems array has the following fields:
name
The name of the peer context for which the values are returned.
val
Returns the value of the counter or level field for the peer statistic. This field returns the statistic's value as maintained by the original supplier of the value. However, the val field is converted to an SPMI data format.
val_change
Returns the difference between the previous reading of the counter and the current reading when the statistic contains counter data. When this value is divided by the elapsed time returned in the SpmiHotSet structure, an event rate-per-time-unit can be calculated.

The RSI Request-Response Interface

The RSI interface API has two distinctly different ways of operation. This section describes the RSI "request-response" protocol that sends a single request to xmservd and waits for a response. A timeout occurs if no response has been received within a specified time limit in which case one single retry is attempted. If the retry also results in a timeout, that fact is communicated to the caller by placing the constant RSiTimeout in the external integer field RSiErrno. If any other error occurred, the external integer field has some other non-zero value.

If neither a communications error nor a timeout occurred, a packet is available in the receive buffer pointed to by the pi pointer in the RSI handle. The packet includes a status code that tells whether the subroutine was successful at the xmservd side. You need only be concerned with checking the status code in a packet if it matters what exactly it is because the constant RSiBadStat is placed in RSiErrno to indicate to your program that a bad status code was received.

You can use the indication of error or success as defined for each subroutine to determine if the subroutine succeeded or you can test the external integerRSiErrno. If this field is RSiOkay the subroutine succeeded; otherwise it did not. The error codes returned in RSiErrno are defined in the enum RSiErrorType.

All the library functions use the request-response interface, except for RSiMainLoop (which uses a network driven interface) and RSiInit, RSiGetValue, and RSiGetRawValue (that do not involve network traffic).

The RSI Network Driven Interface

The xmquery protocol, which is described in detail in "The xmservd Interface", defines three types of data packets that are sent from the data supplier side (xmservd) without being solicited by a request packet. Those packet types are the still_alive, the data_feed, and the except_rec packets. The still_alive packets are handled internally in the RSI interface and require no programming in the data-consumer program.

The data_feed packets are received asynchronously with any packets produced by the request-response type subroutines. If a data_feed packet is received when processing a request-response function, control is passed to a callback function, which must be named when the RSI handle is initialized with the RSiOpen subroutine.

When the data-consumer program is not using the request-response functions, it still needs to be able to receive and process data_feed packets. This is done with the RSiMainLoop function, which invokes the callback function whenever a packet is received.

Actually, the data feed callback function is invoked for all packets received that can not be identified as a response to the latest request sent, except if such packets are of type i_am_back, still_alive, or except_rec. Note that this means that responses to "request-response" packets that arrive after a timeout is sent to the callback function. It is the responsibility of your callback function to test for the packet type received.

The except_rec packets are received asynchronously with any packets produced by the request-response type subroutines. If an except_rec packet is received when processing a request-response function, control is passed to a callback function, which must be named when the RSI handle is initialized with the RSiOpen subroutine.

When the data-consumer program is not using the request-response functions, it still needs to be able to receive and process except_rec packets. This is done with the RSiMainLoop function which invokes the callback function whenever a packet is received.

Note that the API discards except_rec messages from a remote host unless a callback function to process the message type was specified on the RSiOpen subroutine call for that host.

Resynchronizing

Network connections can go bad, hosts can go down, interfaces can be taken down and processes can die. In the case of the xmservd protocol, such situations normally result in one or more of the following:

Missing packets
Responses to outstanding requests are not received, which generate a timeout. That's fairly easy to cope with since the data-consumer program has to handle other error return codes anyway. It also results in expected data feeds not being received. Your program may want to test for this happening. The proper way to handle this situation is to use the RSiClose function to release all memory related to the dead host and to free the RSI handle. After this is done, the data-consumer program may attempt another RSiOpen to the remote system or may simply exit.
Resynchronizing requests
Whenever an xmservd daemon hears from a given data-consumer program on a particular host for the first time, it responds with a packet of type i_am_back, effectively prompting the data-consumer program to resynchronize with the daemon. Also, when the daemon attempts to reconnect to data-consumer programs that it talked to when it was killed or died, it sends an i_am_back packet.

It is important that you understand how the xmservd daemon handles "first time contacted." It is based upon tables internal to the daemon. Those tables identify all the data-consumers that the daemon knows about. Be aware that a data-consumer program is known by the host name of the host where it executes suffixed by the IP port number used to talk to the daemon. Each data-consumer program running is identified uniquely as are multiple running copies of the same data-consumer program.

Whenever a data-consumer program exits orderly, it alerts the daemon that it intends to exit and the daemon removes it from the internal tables. If, however, the data-consumer program decides to not request data feeds from the daemon for some time, the daemon detects that the data consumer has lost interest and removes the data consumer from its tables as described in "Life and Death of xmservd" on page . If the data-consumer program decides later that it wants to talk to the xmservd again, the daemon responds with an i_am_back packet.

The i_am_back packets are given special treatment by the RSI interface. Each time one is received, a resynchronizing callback function is invoked. This function must be defined on the RSiOpen subroutine.

Please note that all data-consumer programs can expect to have this callback invoked once during execution of the RSiOpen subroutine since the remote xmservd does not know the data consumer. This is normal and should not cause your program to panic. If the resynchronize callback is invoked twice during processing of the RSiOpen function, the open failed and can be retried, if appropriate.

A Simple Data-Consumer Program

In this section, we illustrate the use of the API by creating a small data-consumer program to produce a continuous list of statistics from a host. The first version accesses only CPU-related statistics. It assumes you want to get your statistics from the local host unless you specify a host name on the command line. The program continues to display the statistics until it is killed. Source code for the sample program can be found in /usr/samples/perfmgr/RsiCons1.c .

Initializing and Terminating the Program

The main function of the sample program uses the three subroutines as shown in the code segment below. The lines 12 through 15 use any command line argument to override the default host name obtained by the uname function. Then lines 17 through 28 initialize the RSI interface using the RSiInit and RSiOpen subroutines. The program exits if the initialization fails.

[01] extern char   RSiEMsg[];
[02] extern int   RSiErrno;
[03] char   host[64], apath[256], head1[24][10], head2[24][10];
[04] char   *nptr, **navn = &nptr, *dptr, **desc = &dptr;
[05] struct utsname  uname_struct;
[06] RSiHandle   rsh;
[07] struct SpmiStatVals *svp[24];
[08] int     lct = 99, tix = 0;
[09]
[10] main(int argc, char **argv)
[11] {
[12]     uname(&uname_struct);
[13]     strcpy(host, uname_struct.nodename);
[14]     if (argc >
 1)
[15]        strcpy(host, argv[1]);
[16]
[17]     if (!(rsh = RSiInit(1)))
[18]     {
[19]        fprintf(stderr, "Unable to initialize RSI interface\n");
[20]        exit(98);
[21]     }
[22]     if (RSiOpen(rsh, 100, 2048, host, feeding, resync, NULL))
[23]     {
[24]        if (strlen(RSiEMsg))
[25]           fprintf(stderr, "%s", RSiEMsg);
[26]        fprintf(stderr, "Error contacting host 
\"%s\"\n", host);
[27]        exit(-99);
[28]     }
[29]     signal(SIGINT, must_exit);
[30]     signal(SIGTERM, must_exit);
[31]     signal(SIGSEGV, must_exit);
[32]     signal(SIGQUIT, must_exit);
[33]
[34]     strcpy(apath, "hosts/");
[35]     strcat(apath, host);
[36]     strcat(apath, "/");
[37]     lststats(apath);
[38]     RSiClose(rsh);
[39]     exit(0);
[40] }

The following lines (29-32) make sure that the program detects any attempt to kill or terminate it. If this happens, the function must_exit is invoked. This function has the sole purpose of making sure the association with the xmservd daemon is terminated. It does this as shown in the following piece of code:

void must_exit()
{
   RSiClose(rsh);
   exit(-9);
}

Finally, lines 34 through 36 prepare an initial value path name for the main processing loop of the data-consumer program. This is the way all value path names should be prepared. After doing this, the main processing loop in the internal function lststats is called. If, against odds, this function returns, we issue an RSiClose call and exit the program.

Defining a Statset

It is the intention that our sample data-consumer program eventually is able to receive data feeds from the xmservd daemon so we might as well start preparing the SpmiStatSet, which defines the set of statistics we are interested in. This is done with the RSiCreateStatSet subroutine .

[01] voidlststats(char *basepath)
[02] {
[03]    struct SpmiStatSet *ssp;
[04]    char     tmp[128];
[05]
[06]    if (!(ssp = RSiCreateStatSet(rsh)))
[07]    {
[08]       fprintf(stderr, "RsiCons1 can\'t create StatSet\n");
[09]       exit(62);
[10]    }
[11]
[12]    strcpy(tmp, basepath);
[13]    strcat(tmp, "CPU/cpu0");
[14]    if ((tix = addstat(tix, ssp, tmp, "cpu0")) == -1)
[15]    {
[16]       if (strlen(RSiEMsg))
[17]          fprintf(stderr, "%s", RSiEMsg);
[18]       exit(63);
[19]    }
[20]
[21]    RSiStartFeed(rsh, ssp, 1000);
[22]    while(TRUE)
[23]       RSiMainLoop(499);
[24] }

In our sample program, the SpmiStatSet is created in the local function lststats shown above in lines 6 through 10.

Lines 12 through 19 invoke the local function addstat, which finds all the CPU-related statistics in the context hierarchy and initializes the arrays to collect and print the information. The first two lines expand the value path name passed to the function by appending CPU/cpu0. The resulting string is the path name of the context where all CPU-related statistics for "cpu0" are held. The path name has the format hosts/hostname/CPU/cpu0 without a terminating slash, which is what is expected by the subroutines that take a value path name as an argument. The function addstat is shown in the next section. It uses three of the traversal functions to access the CPU-related statistics.

Adding Statistics to the Statset

[01] int addstat(int ix, struct SpmiStatSet *ssp, char *path, char *txt)
[02] {
[03]    cx_handle   *cxh;
[04]    int     i = ix;
[05]    char     tmp[128];
[06]    struct SpmiStatLink *statlink;
[07]
[08]    if (!(cxh = RSiPathGetCx(rsh, path)))
[09]    {
[10]       fprintf(stderr, "RSiPathGetCx can\'t access host %s (path 
%s)\n", host, path);
[11]       exit(61);
[12]    }
[13]
[14]    if ((statlink = RSiFirstStat(rsh, cxh, navn, desc)))
[15]    {
[16]       while (statlink)
[17]       {
[18]          if (i >
 23)
[19]              break;
[20]          strcpy(head1[i], txt);
[21]          strcpy(head2[i], *navn);
[22]          strcpy(tmp, path);
[23]          strcat(tmp, "/");
[24]          strcat(tmp, *navn);
[25]          if (!(svp[i] = RSiPathAddSetStat(rsh, ssp, tmp)))
[26]             return(-1);
[27]          i++;
[28]          statlink = RSiNextStat(rsh, cxh, statlink, navn, desc);
[29]       }
[30]    }
[31]  return(i);
[32] }

The use of RSiPathGetCx by the sample program is shown in lines 8 through 12 . Following that, in lines 14 through 30, two subroutines are used to get all the statistics values defined for the CPU context. This is done by using RSiFirstStat and RSiNextStat.

In lines 20-21, the short name of the context ("cpu0") and the short name of the statistic are saved in two arrays for use when printing the column headings. Lines 22-24 construct the full path name of the statistics value by concatenating the full context path name and the short name of the value. This is necessary to proceed with adding the value to the SpmiStatSet with the subroutine RSiPathAddSetStat . The value is added by lines 25 and 26.

Data-Consumer Initialization of Data Feeds

The only part of the main processing function in the main section yet to explain consists of lines 21 through 23. The first line simply tells the xmservd daemon to start feeding observations of statistics for an SpmiStatSet by issuing the RSiStartFeed subroutine call. The next two lines define an infinite loop that calls the function RSiMainLoop to check for incoming data_feed packets.

There are two more subroutines concerned with controlling the flow of data feeds from xmservd. Neither is used in the sample program. The subroutines are described in RSiChangeFeed and RSiStopFeed.

Data-Consumer Decoding of Data Feeds

Whenever a data_feed is detected by the RSI interface, the data feed callback function defined in the RSiOpen subroutine is invoked, passing the RSI handle as an argument to the callback function. Our sample program's callback function for data feeds is shown below. Most of the lines in the function are concerned with printing headings after each 20 detail lines printed. This is in line numbers 9 through 19 and 26.

[01] void feeding(RSiHandle rsh, pack *p)
[02] {
[03]    int  i;
[04]    float f;
[05]    long  v;
[06]
[07]    if (p->
type != data_feed)
[08]       return;
[09]    if (lct >
 20)
[10]    {
[11]       printf("\n\n");
[12]       for (i = 0; i < tix; i++)
[13]          printf("%08s", head1[i]);
[14]       printf("\n");
[15]       for (i = 0; i < tix; i++)
[16]          printf("%08s", head2[i]);
[17]       printf("\n");
[18]       lct = 0;
[19]    }
[20]    for (i = 0; i < tix; i++)
[21]    {
[22]       v = RSiGetValue(rsh, svp[i]) * 10.0;
[23]       printf("%6d.%d", v/10, v%10);
[24]    }
[25]    printf("\n");
[26]    lct++;
[27] }

Actual processing of received statistics values is done by the lines 20-24. It involves the use of the library subroutine RSiGetValue. The following is an example of output from the sample program RsiCons1 when executed against an AIX Version 3.2 system.

$ RsiCons1 umbra

    cpu0    cpu0    cpu0    cpu0    cpu0    cpu0    cpu0    cpu0
    user    kern    wait    idle  uticks  kticks  wticks  iticks
     0.0     0.0     0.0   100.0     0.0     0.0     0.0   100.0
     0.0     0.0     0.0   100.0     0.0     0.0     0.0    99.9
     0.2     3.1     0.0    96.5     0.2     3.2     0.0    96.6
     3.5     5.5     1.5    89.1     3.5     5.5     1.5    89.1
     5.8     3.4     0.0    90.8     5.8     3.4     0.0    90.8
     8.8     8.3     0.1    82.5     8.8     8.3     0.2    82.5
    67.5     2.4     3.0    27.0    67.5     2.3     2.9    26.9
    16.0     0.6     0.8    82.5    16.0     0.6     0.8    82.6
    67.5     5.0     0.0    27.3    67.5     5.0     0.0    27.3
    19.0     6.1     0.9    73.8    19.1     6.1     0.9    73.8
    22.5     0.8     1.6    75.0    22.5     0.8     1.6    74.9
    60.2     6.1     0.0    33.5    60.2     6.1     0.0    33.5
$

An Alternative Way to Decode Data Feeds

If you need to know more about the data received in data_feed packets than what RSiGetValue gives you, you can use the library subroutine RSiGetRawValue.

Expanding the Data-Consumer Program

A slightly more capable version of the sample program discussed in the previous sections is provided as /usr/samples/perfmgr/RsiCons.c. This program also lists the statistics with the short name xfer for all the disks found in the system where the daemon runs. To do so, the program uses some additional subroutines to traverse contexts as described in the following section.

Traversing Contexts

The function adddisk listed below shows how the RSiFirstCx, RSiNextCx, and the RSiInstantiate subroutines are combined with RSiPathGetCx to make sure all subcontexts are accessed. The sample program's internal function addstat is used to add the statistics of each subcontext to the SpmiStatSet in turn. A programmer who wanted to traverse all levels of subcontexts below a start context could easily create a recursive function to do this.

[01] int adddisk(int ix, struct SpmiStatSet *ssp, char *path)
[02] {
[03]    int     i = ix;
[04]    char     tmp[128];
[05]    cx_handle   *cxh;
[06]    struct SpmiStatLink *statlink;
[07]    struct SpmiCxLink *cxlink;
[08]
[09]    cxh = RSiPathGetCx(rsh, path);
[10]    if ((!cxh) || (!cxh->
cxt))
[11]    {
[12]       if (strlen(RSiEMsg))
[13]          fprintf(stderr, "%s", RSiEMsg);
[14]       fprintf(stderr, "RSiPathGetCx can\'t access host %s (path 
%s)\n",
[15]       host, path);
[16]       exit(64);
[17]    }
[18]    if (rsh->
pi->
data.getcx.context.inst_freq == SiContInst)
[19]    {
[20]       if ((i = RSiInstantiate(rsh, cxh)))
[21]          return(-1);
[22]    }
[23]    if ((cxlink = RSiFirstCx(rsh, cxh, navn, desc)))
[24]    {
[25]       while (cxlink)
[26]       {
[27]         strcpy(tmp, path);
[28]         if (strlen(tmp))
[29]            strcat(tmp, "/");
[30]         if (*navn)
[31]            strcat(tmp, *navn);
[32]         if ((i = addstat(i, ssp, tmp, *navn)) == -1)
[33]         {
[34]            if (strlen(RSiEMsg))
[35]               fprintf(stderr, "%s", RSiEMsg);
[36]            exit(63);
[37]         }
[38]         cxlink = RSiNextCx(rsh, cxh, cxlink, navn, desc);
[39]       }
[40]    }
[41]    return(i);
[42] }

Below is the output from the RsiCons program when xmservd runs on an AIX Version 4.1 host.

$ RsiCons encee

     CPU     CPU     CPU     CPU  hdisk3  hdisk1  hdisk0     cd0
  uticks  kticks  wticks  iticks    xfer    xfer    xfer    xfer
    19.6    10.0     4.1    67.1     2.7     4.1     0.0     0.0
    10.9    15.3     8.2    65.3     0.0     8.2     0.0     0.0
     0.5     2.0     0.0    97.5     0.0     0.0     0.0     0.0
    10.5     4.0     0.0    85.5     0.0     0.0     0.0     0.0
    55.4     8.9     0.0    35.4     2.4     0.0     0.0     0.0
    19.0     5.5     0.0    75.5     0.0     0.0     0.0     0.0
     5.9     6.4     0.0    87.4     0.0     0.0     0.0     0.0
    10.5     7.0     0.0    82.5     0.0     0.0     0.0     0.0
     7.9     7.4     0.0    84.4     0.0     0.0     0.0     0.0
    88.5     8.5     3.0     0.0     9.5     4.5     0.0     0.0
    89.4     8.9     1.4     0.0     5.9     0.0     0.0     0.0
    92.5     5.5     2.0     0.0     9.0     8.5     0.0     0.0
    71.0     6.0    23.0     0.0    44.0    41.0     0.0     0.0
    37.9     2.4    58.9     0.4    67.9    61.4     0.0     0.0
    17.5     4.5     0.0    78.0     1.5     3.0     0.0     0.0
     0.5     1.5    10.0    88.0     7.5     1.5     0.0     0.0
$

Inviting Data Suppliers

Sometimes you want to design programs that can present the end user with a list of potential data-supplier hosts rather than requiring the user to specify which host to monitor. The RSiInvite allows you to create such programs.

Identifying Data Suppliers

The RSiInvite subroutine uses one or more of the following methods to obtain the Internet addresses to which an invitational are_you_there message can be sent. The last two methods depend on the presence of the $HOME/Rsi.hosts file. PTX also has alternative locations of the Rsi.hosts file. The three ways to invite data-supplier hosts are:

  1. Unless instructed not to by the user, the broadcast address corresponding to each of the network interfaces of the local host is found. The invitational message is sent on each network interface using the corresponding broadcast address. Broadcasts are not attempted on the Localhost (loopback) interface or on point-to-point interfaces such as X.25 or SLIP (Serial Line Interface Protocol) connections.
  2. If a list of Internet broadcast addresses is supplied in the file $HOME/Rsi.hosts , an invitational message is sent on each such broadcast address. Note that if you specify the broadcast address of a local interface, broadcasts are sent twice on those interfaces. You may want to use this as a feature in order to minimize the likelihood of the invitation being lost.
  3. If a list of host names is supplied in the file $HOME/Rsi.hosts , the host Internet address for each host in the list is looked up and a message is sent to each host. The look-up is done through a gethostbyname() call, so that whichever name service is active for the host where the data-consumer application runs is used to find the host address.

The file $HOME/Rsi.hosts has a very simple layout. Only one keyword is recognized and only if placed in column one of a line. That keyword is:

nobroadcast

and means that the are_you_there message should not be broadcast using method 1 above. This option is useful in situations where a large number of hosts are on the network and only a well-defined subset should be remotely monitored. To say that you don't want broadcasts but want direct contact to three hosts, your $HOME/Rsi.hosts file might look like this:

nobroadcast
birte.austin.ibm.com
gatea.almaden.ibm.com
umbra

This example shows that the hosts to monitor do not necessarily have to be in the same domain or on a local network. However, doing remote monitoring across a low-speed communications line is not likely to be very popular; neither with other users of that communications line nor with yourself.

Be aware that whenever you want to monitor remote hosts that are not on the same subnet as the data-consumer host, you must specify the broadcast address of the other subnets or all the host names of those hosts in the $HOME/Rsi.hosts file. The reason is that IP broadcasts do not propagate through IP routers or gateways.

The following example illustrates a situation where you want to do broadcasting on all local interfaces, want to broadcast on the subnet identified by the broadcast address 129.49.143.255, and also want to invite the host called umbra. (The subnet mask corresponding to the broadcast address in this example is 255.255.240.0 and the range of addresses covered by the broadcast is 129.49.128.0 - 129.49.143.255.)

129.49.143.255

If the RSiInvite subroutine detects that the name server is inoperational or has abnormally long response time, it returns the Internet addresses of hosts rather than the host names. If the name server fails after the list of hosts is partly built, the same host may appear twice, once with its Internet address and once with its host name.

The execution time of the RSiInvite subroutine depends primarily on the number of broadcast addresses you place in the $HOME/Rsi.hosts file. Each broadcast address increases the execution time with roughly 50 milliseconds plus the time required to process the responses. The minimum execution time of the subroutine is roughly 1.5 seconds, during which time your application only gets control if callback functions are specified and if packets arrive that must be given to those callback functions.

A Full-Screen, Character-based Monitor

Another sample program written to the data-consumer API is the program chmon. Source code to the program is in /usr/samples/perfmgr/chmon.c . The chmon program is also stored as an executable during the installation of the Manager component. This program uses the API and the curses programming interface to create a screen full of statistics as shown below:

Data-Consumer API       Remote Monitor for host     Tue Apr 14 09:09:05 
1992
CHMON Sample Program       ***   birte  ***         Interval:      5 seconds

% CPU                                            EVENTS/QUEUES  FILE/TTY
Kernel  13.3   |####                           | Pswitch  1295  Readch 24589
User    23.7   |#######                        | Syscall  6173  Writech 1646
Wait     6.5   |##                             | Reads     487  Rawin      0
Idle    56.1   |################               | Writes    143  Ttyout   106
                                                 Forks       1  Igets   1763
PAGING counts   PAGING SPACE   REAL MEM  48MB    Execs       1  Namei    809
Faults    131   % Used  33.7   % Comp    68.0    Runqueue    1  Dirblk   174
Steals      0   % Free  66.2   % NonComp 15.0    Swapqueue   0  Reads     48
Reclaim     0   Size,MB   96   % Client   4.0                   Writes   143

PAGING page/s   DISK       Read  Write     %     NETWORK   Read  Write
Pgspin      0   ACTIVITY KB/sec  KB/sec  Busy    ACTIVITY KB/sec KB/sec
Pgspout     0   hdisk0      0.0    35.1  15.7    lo0         1.1    1.1
Pagein      0   hdisk1      0.0     0.0   0.0    tr0         1.1    0.0
Pageout    11   hdisk2      0.0     9.5   3.5
Sios       10   cd1         0.0     0.0   0.0

      Process wait     (514)   %cpu 63.2, PgSp: 0.0mb, uid:
      Process xlcentry (12657) %cpu 58.0, PgSp: 1.1mb, uid: birte
      Process make     (21868) %cpu 15.0, PgSp: 0.2mb, uid: birte
      Process make     (5998)  %cpu 15.0, PgSp: 0.1mb, uid: birte

The chmon command line is:

chmon[-iseconds_interval][-pno_of_processes][hostname]

where:

seconds_interval
Is the interval between observations. Must be specified in seconds. No blanks must be entered between the flag and the interval. Defaults to 5 seconds.
no_of_processes
Is the number of "hot" processes to be shown. A process is considered "hotter" the more CPU it uses. No blanks must be entered between the flag and the count field. Defaults to 0 (no) processes.
hostname
Is the host name of the host to be monitored. Default is the local host.

The sample program exits after 2,000 observations have been taken, or when you type the letter "q" in its window.

RSi Subroutines

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 be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

HotSet
Specifies a pointer to a valid structure of type SpmiHotSet as created by the RSiCreateHotSet 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 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:

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

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.

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 RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateHotSetsubroutine , RSiOpen subroutine .


RSiChangeFeed Subroutine

Purpose

Changes the frequency at which the xmservd on the host identified by the first argument daemon is sending data_feed packets for a statset.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiChangeFeed(rhandle, statset, msecs)
RSiHandle rhandle;struct SpmiStatSet *statset;int msecs;

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

statset
Must be a pointer to a structure of type struct SpmiStatSet, which was previously returned by a successful RSiCreateStatSet subroutine call. Data feeding must have been started for this SpmiStatSet via a previous RSiStartFeed subroutine call.

msecs
The number of milliseconds between the sending of data_feed packets. This number is rounded to a multiple of min_remote_int milliseconds by the xmservd daemon on the remote host. This minimum interval can be modified through the -i command line interval to xmservd.

Return Values

If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateStatSet subroutine , RSiOpen subroutine , RSiStartFeed subroutine .


RSiChangeHotFeed Subroutine

Purpose

Changes the frequency at which the xmservd on the host identified by the first argument daemon is sending hot_feed packets for a statset or checking if exceptions or SNMP traps should be generated.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiChangeFeed(rhandle, hotset, msecs)
RSiHandle rhandle;struct SpmiHotSet *hotset;int msecs;

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

hotset
Must be a pointer to a structure of type struct SpmiHotSet, which was previously returned by a successful RsiCreateHotSet subroutine call. Data feeding must have been started for this SpmiHotSet via a previous RSiStartHotFeed subroutine call.

msecs
The number of milliseconds between the sending of Hot_feed packets. This number is rounded to a multiple of min_remote_int milliseconds by the xmservd daemon on the remote host. This minimum interval can be modified through the -i command line interval to xmservd.

Return Values

If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateHotSet subroutine , RSiOpen subroutine , RSiStartHotFeed subroutine .


RSiClose Subroutine

Purpose

Terminates the RSI interface for a remote host connection.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
void RSiClose(rhandle)
RSiHandle rhandle;

Description

The RSiClose subroutine is responsible for:

  1. Removing the data-consumer program as a known data consumer on a particular host. This is done by sending a going_down packet to the host.
  2. Marking the RSI handle as not active.
  3. Releasing all memory allocated in connection with the RSI handle.
  4. Terminating the RSI interface for a remote host.

A successful RSiOpen subroutine creates tables on the remote host it was issued against. Therefore, a data consumer program that has issued successful RSiOpen subroutine calls should issue an RSiClose subroutine call for each RSiOpen call before the program exits so that the tables in the remote xmservd daemon can be released.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

The macro RSiIsOpen can be used to test whether an RSI handle is open. It takes an RSiHandle as argument and returns true (1) if the handle is open, otherwise false (0).

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiInit subroutine, RSiOpen subroutine.


RSiCreateHotSet Subroutine

Purpose

Creates an empty hotset on the remote host identified by the argument.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiHotSet *RSiCreateHotSet(rhandle)
RSiHandle rhandle;

Description

The RSiCreateHotSet subroutine allocates an SpmiHotSet structure. The structure is initialized as an empty SpmiHotSet and a pointer to the SpmiHotSet structure is returned.

The SpmiHotSet structure provides the anchor point to a set of peer statistics and must exist before the RSiAddSetHot subroutine can be successfully called.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

Return Values

The RSiCreateHotSet subroutine returns a pointer to a structure of type SpmiHotSet if successful. If unsuccessful, the subroutine returns a NULL value.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiAddSetHot subroutine .


RSiCreateStatSet Subroutine

Purpose

Creates an empty statset on the remote host identified by the argument.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiStatSet *RSiCreateStatSet(rhandle)
RSiHandle rhandle;

Description

The RSiCreateStatSet subroutine allocates an SpmiStatSet structure. The structure is initialized as an empty SpmiStatSet and a pointer to the SpmiStatSet structure is returned.

The SpmiStatSet structure provides the anchor point to a set of statistics and must exist before the RSiPathAddSetStat subroutine can be successfully called.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

Return Values

The RSiCreateStatSet subroutine returns a pointer to a structure of type SpmiStatSet if successful. If unsuccessful, the subroutine returns a NULL value.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiPathAddSetStat subroutine .


RSiDelSetHot Subroutine

Purpose

Deletes a single set of peer statistics identified by an SpmiHotVals structure from an SpmiHotSet.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiDelSetHot(rhandle, hsp, hvp)
RSiHandle rhandle;struct SpmiHotSet *hsp;struct SpmiHotVals *hvp;

Description

The RSiDelSetHot subroutine performs the following actions:

  1. Validates that the SpmiHotSet identified by the second argument exists and contains the SpmiHotVals statistic identified by the third argument.
  2. Deletes the SpmiHotVals value from the SpmiHotSet so that future data_feed packets do not include the deleted statistic.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

hsp
Must be a pointer to a structure type struct SpmiHotSet, which was previously returned by a successful RSiCreateHotSet subroutine call.

hvp
Must be a handle of type struct SpmiHotVals as returned by a successful RSiAddSetHot subroutine call. You can not specify an SpmiHotVals that was internally generated by the Spmi library code as described under the GrandParent parameter to RSiAddSetHot.

Return Values

If successful, the subroutine returns a zero value; otherwise it returns a non-zero value and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateHotSet subroutine , RSiOpen subroutine , RSiAddSetHot subroutine .


RSiDelSetStat Subroutine

Purpose

Deletes a single statistic identified by an SpmiStatVals pointer from an SpmiStatSet.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiDelSetStat(rhandle, ssp, svp)
RSiHandle rhandle;struct SpmiStatSet *ssp;struct SpmiStatVals *svp;

Description

The RSiDelSetStat subroutine performs the following actions:

  1. Validates the SpmiStatSet identified by the second argument exists and contains the SpmiStatVals statistic identified by the third argument.
  2. Deletes the SpmiStatVals value from the SpmiStatSet so that future data_feed packets do not include the deleted statistic.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

ssp
Must be a pointer to a structure type struct SpmiStatSet, which was previously returned by a successful RSiCreateStatSet subroutine call.

svp
Must be a handle of type struct SpmiStatVals as returned by a successful RSiPathAddSetStat subroutine call.

Return Values

If successful, the subroutine returns a zero value; otherwise it returns a non-zero value and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateStatSet subroutine , RSiOpen subroutine , RSiPathAddSetStat subroutine .


RSiFirstCx Subroutine

Purpose

Returns the first subcontext of an SpmiCx context.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiCxLink *RSiFirstCx(rhandle, context, name, 
descr)
RSiHandle rhandle;
cx_handle *context;
char **name;
char **descr;

Description

The RSiFirstCx subroutine performs the following actions:

  1. Validates that the context identified by the second argument exists.
  2. Returns a handle to the first element of the list of subcontexts defined for the context.
  3. Returns the short name and description of the subcontext.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

context
Must be a handle of type cx_handle, which was previously returned by a successful RSiPathGetCx subroutine call.

name
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the short name of the subcontext is returned in the character array pointer.

descr
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the description of the subcontext is returned in the character array pointer.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiCxLink. If an error occurs or if the context doesn't contain subcontexts, NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiNextCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .


RSiFirstStat Subroutine

Purpose

Returns the first statistic of an SpmiCx context.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiStatLink *RSiFirstStat(rhandle, context, name, 
descr)
RSiHandle rhandle;
cx_handle *context;
char **name;
char **descr;

Description

The RSiFirstStat subroutine performs the following actions:

  1. Validates that the context identified by the second argument exists.
  2. Returns a handle to the first element of the list of statistics defined for the context.
  3. Returns the short name and description of the statistic.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

context
Must be a handle of type cx_handle, which was previously returned by a successful RSiPathGetCx subroutine call.

name
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the short name of the statistics value is returned in the character array pointer.

descr
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the description of the statistics value is returned in the character array pointer.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiStatLink. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiNextStat subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .


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. Since 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. Succesful 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.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.
HotSet
Used to return a pointer to a valid SpmiHotSet structure as obtained by a previous RSiCreateHotSet 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:
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 invalid 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 RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiCreateHotSet subroutine .


RSiGetRawValue Subroutine

Purpose

Returns a pointer to a valid SpmiStatVals structure for a given SpmiStatVals pointer by extraction from a data_feed packet. This subroutine call should only be issued from a callback function after it has been verified that a data_feed packet was received from the host identified by the first argument.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiStatVals RSiGetRawValue(rhandle, svp, index)
RSiHandle rhandle;
struct SpmiStatVals *svp;
int *index;

Description

The RSiGetRawValue subroutine performs the following:

  1. Finds an SpmiStatVals structure in the received data packet based upon the second argument to the subroutine call. This involves a lookup operation in tables maintained internally by the RSi interface.
  2. Updates the struct SpmiStat pointer in the SpmiStatVals structure to point at a valid SpmiStat structure.
  3. Returns a pointer to the SpmiStatVals structure. The returned pointer points to a static area and is only valid until the next execution of RSiGetRawValue.
  4. Updates an integer variable with the index into the ValsSet array of the data_feed packet, which corresponds to the second argument to the call.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

svp
A handle of type struct SpmiStatVals, which was previously returned by a successful RSiPathAddSetStat subroutine call.

index
A pointer to an integer variable. When the subroutine call succeeds, the index into the ValsSet array of the data feed packet is returned. The index corresponds to the element that matches the svp argument to the subroutine.

Return Values

If successful, the subroutine returns a pointer; otherwise NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiGetRawValue subroutine , RSiOpen subroutine , RSiPathAddSetStat subroutine .


RSiGetValue Subroutine

Purpose

Returns a data value for a given SpmiStatVals pointer by extraction from the data_feed packet. This subroutine call should only be issued from a callback function after it has been verified that a data_feed packet was received from the host identified by the first argument.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
float RSiGetValue(rhandle, svp)
RSiHandle rhandle;
struct SpmiStatVals *svp;

Description

The RSiGetValue subroutine provides the following:

  1. Finds an SpmiStatVals structure in the received data packet based upon the second argument to the subroutine call. This involves a lookup operation in tables maintained internally by the RSi interface.
  2. Determines the format of the data field as being either SiFloat or SiLong and extracts the data value for further processing based upon its data format.
  3. Determines the value as either of type SiQuantity or SiCounter. If the former is the case, the data value returned is the val field in the SpmiStatVals structure. If the latter type is found, the value returned by the subroutine is the val_change field divided by the elapsed number of seconds since the previous data packet's time stamp.

Parameters

rhandle
Must be an RSiHandle, previously initialized by the RSiOpen subroutine.

svp
A handle of type struct SpmiStatVals, which was previously returned by a successful RSiPathAddSetStat subroutine call.

Return Values

If successful, the subroutine returns a non-negative value; otherwise it returns a negative value less than or equal to -1.0. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiPathAddSetStat subroutine .


RSiInit Subroutine

Purpose

Allocates or changes the table of RSi handles.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
RSiHandle RSiInit(count)
int count;

Description

Before any other RSi call is executed, a data-consumer program must issue the RSiInit call. Its purpose is to either:

Parameters

count
Must specify the number of elements in the array of RSi handles. If the call is used to expand a previously allocated array, this argument must be larger than the current number of array elements. It must always be larger than zero. You should specify the size of the array to be at least as large as the number of hosts your data-consumer program can talk to at any point in time.

Return Values

If successful, the subroutine returns the address of the allocated array. If an error occurs, an error text is placed in the external character array RSiEMsg and the subroutine returns NULL. When used to increase the size of a previously allocated array, the subroutine first allocates the new array, then moves the entire old array to the new area. Application programs should, therefore, refer to elements in the RSi handle array by index rather than by address if they anticipate the need for expanding the array. The array only needs to be expanded if the number of remote hosts a data-consumer program talks to might increase over the life of the program.

An application that calls RSiInit repeatedly needs to preserve the previous address of the RSiHandle array while the RSiInit call is re-executed. After the call has completed successfully, the calling program should free the previous array using the free subroutine.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiClose subroutine .


RSiInstantiate Subroutine

Purpose

Creates (instantiates) all subcontexts of an SpmiCx context object.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiInstantiate(rhandle, context)
RSiHandle rhandle;
cx_handle *context;

Description

The RSiInstantiate subroutine performs the following actions:

  1. Validates that the context identified by the second argument exists.
  2. Instantiates the context so that all subcontexts of that context are created in the context hierarchy. Note that this subroutine call currently only makes sense if the context's SiInstFreq is set to SiContInst or SiCfgInst since all other contexts would have been instantiated whenever the xmservd daemon was started.

The RSiInstantiate subroutine explicitly instantiates the subcontexts of an instantiable context. If the context is not instantiable, do not call the RSiInstantiate subroutine.

Parameters

rhandle
Must point to a structure of type RSiHandle, which was previously initialized by the RSiOpen subroutine.

context
Must be a handle of type cx_handle, which was previously returned by a successful RSiPathGetCx subroutine call.

Return Values

If successful, the subroutine returns a zero value; otherwise it returns an error code as defined in SiError and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiFirstCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .


RSiInvite Subroutine

Purpose

Invites data suppliers on the network to identify themselves and returns a table of data-supplier host names.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
char **RSiInvite(resy_callb, excp_callb)
int (*resy_callb)();
int (*excp_callb)();

Description

The RSiInvite subroutine call broadcasts are_you_there messages on the network to provoke xmservd daemons on remote hosts to respond and returns a table of all responding hosts.

Parameters

The arguments to the subroutine are:

resy_callb
Must be either NULL or a pointer to a function that processes i_am_back packets as they are received from the xmservd daemons on remote hosts for the duration of the RSiInvite subroutine call. When the callback function is invoked it is passed three arguments as described below.

If this argument is specified as NULL, a callback function internal to the RSiInvite subroutine receives any i_am_back packets and uses them to build the table of host names the function returns.

excp_callb
Must be NULL or a pointer to a function that processes except_rec packets as they are received from the xmservd daemons on remote hosts. If a NULL pointer is passed, your application does not receive except_rec messages. When this callback function is invoked it is passed three arguments as described below.

This argument always overrides the corresponding argument of any previous RSiInvite or RSiOpen call and may itself be overridden by subsequent executions of either. In this way, your application can turn exception monitoring on and off. For an RSiOpen to override the exception processing specified by a previous open call, the connection must first be closed with the RSiClose call. That's because an RSiOpen against an already active handle is treated as a no-operation.

The resy_callb and excp_callb functions in your application are called with the following three arguments:

Return Values

If successful, the subroutine returns an array of character pointers, each of which contains a host name of a host that responded to the invitation. The returned host names are actually constructed as two "words" with the first one being the host name returned by the host in response to an are_you_there request; the second one being the character form of the host's Internet address. The two "words" are separated by one or more blanks. This format is suitable as an argument to the RSiOpen subroutine call. In addition, the external integer variable RSiInvTabActive contains the number of host names found. The returned pointer to an array of host names must not be freed by the subroutine call. The calling program should not assume that the pointer returned by this subroutine call remains valid after subsequent calls to RSiInvite. If the call is not successful, an error text is placed in the external character array RSiEMsg, an error number is placed in RSiErrno, and the subroutine returns NULL.

The list of host names returned by RSiInvite does not include the hosts your program has already established a connection with through an RSiOpen call. Your program is responsible for keeping track of such hosts. If you need a list of both sets of hosts, either let the RSiInvite call be the first one issued from your program or merge the list of host names returned by the call with the list of hosts to which you have connections.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine .


RSiMainLoop Subroutine

Purpose

Allows an application to suspend execution and wait to get awakened when data feeds arrive.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
void RSiMainLoop(msecs)
int msecs;

Description

The RSiMainLoop subroutine:

  1. Allows the data-consumer program to suspend processing while waiting for data_feed packets to arrive from one or more xmservd daemons.
  2. Tells the subroutine that waits for data feeds to return control to the data-consumer program so that the latter can check for and react to other events.
  3. Invokes the subroutine to process data_feed packets for each such packet received.

To work properly, the RSiMainLoop subroutine requires that at least one RSiOpen call has been successfully completed and that the connection has not been closed.

Parameters

msecs
The minimum elapsed time in milliseconds that the subroutine should continue to attempt receives before returning to the caller. Notice that your program releases control for as many milliseconds you specify but that the callback functions defined on the RSiOpen call may be called repetitively during that time.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine .


RSiNextCx Subroutine

Purpose

Returns the next subcontext of an SpmiCx context.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiCxLink *RSiNextCx(rhandle, context, link, name, 
descr)
RSiHandle rhandle;
cx_handle *context;
struct SpmiCxLink *link;
char **name;
char **descr;

Description

The RSiNextCx subroutine:

  1. Validates that the context identified by the second argument exists.
  2. Returns a handle to the next element of the list of subcontexts defined for the context.
  3. Returns the short name and description of the subcontext.

Parameters

rhandle
Must point to a structure of type RSiHandle, which was previously initialized by the RSiOpen subroutine.

context
Must be a handle of type cx_handle, which was previously returned by a successful RSiPathGetCx subroutine call.

link
Must be a pointer to a structure of type struct SpmiCxLink, which was previously returned by a successful RSiFirstCx or RSiNextCx subroutine call.

name
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the short name of the subcontext is returned in the character array pointer.

descr
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the description of the subcontext is returned in the character array pointer.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiCxLink. If an error occurs, or if no more subcontexts exist for the context, NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiFirstCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .


RSiNextStat Subroutine

Purpose

Returns the next statistic of an SpmiCx context.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiStatLink *RSiNextStat(rhandle, context, link, name, 
descr)
RSiHandle rhandle;
cx_handle *context;
struct SpmiStatLink *link;
char **name;
char **descr;

Description

The RSiNextStat subroutine:

  1. Validates that a context identified by the second argument exists.
  2. Returns a handle to the next element of the list of statistics defined for the context.
  3. Returns the short name and description of the statistic.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

context
Must be a handle of type cx_handle, which was previously returned by a successful RSiPathGetCx subroutine call.

link
Must be a pointer to a structure of type struct SpmiStatLink, which was previously returned by a successful RSiFirstStat or RSiNextStat subroutine call.

name
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the short name of the statistics value is returned in the character array pointer.

descr
Must be a pointer to a pointer to a character array. The pointer must be initialized to point at a character array pointer. When the subroutine call is successful, the description of the statistics value is returned in the character array pointer.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiStatLink. If an error occurs, or if no more statistics exists for the context, NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiFirstStat subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .


RSiOpen Subroutine

Purpose

Initializes the RSi interface for a remote host.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiOpen(rhandle, wait, bufsize, hostID, feed_callb,
            resy_callb, excp_callb)
RSiHandle rhandle;
int wait;
int bufsize;
char *hostID;
int (*feed_callb)();
int (*resy_callb)();
int (*excp_callb)();

Description

The RSiOpen subroutine performs the following actions:

  1. Establishes the issuing data-consumer program as a data consumer known to the xmservd daemon on a particular host. The subroutine does this by sending an are_you_there packet to the host.
  2. Initializes an RSi handle for subsequent use by the data-consumer program.

Parameters

The arguments to the subroutine are:

rhandle
Must point to an element of the RSiHandleStruct array, which is returned by a previous RSiInit call. If the subroutine is successful the structure is initialized and ready to use as a handle for subsequent RSi interface subroutine calls.

wait
Must specify the timeout in milliseconds that the RSi interface shall wait for a response when using the request-response functions. On LANs, a reasonable value for this argument is 100 milliseconds. If the response is not received after the specified wait time, the library subroutines retry the receive operation until five times the wait time has elapsed before returning a timeout indication. The wait time must be zero or more milliseconds.

bufsize
Specifies the maximum buffer size to be used for constructing network packets. This size must be at least 4,096 bytes. The buffer size determines the maximum packet length that can be received by your program and sets the limit for the number of data values that can be received in one data_feed packet. There's no point in setting the buffer size larger than that of the xmservd daemon since both must be able to handle the packets. If you need large sets of values, you can use the command line argument -b of xmservd to increase its buffer size up to 16,384 bytes.

The fixed part of a data_feed packet is 104 bytes and each value takes 32 bytes. A buffer size of 4,096 bytes allows up to 124 values per packet.

hostID
Must be a character array containing the identification of the remote host whose xmservd daemon we want to talk to. The first "word" of the host identification (up to the first white space) is used as the host name. The full host identification is stored in the RSiHandle field longname and may contain any description that helps the end user identify the host used. The host name may be either in long format (including domain name) or in short format.

feed_callb
Must be a pointer to a function that processes data_feed packets as they are received from the xmservd daemon. When this callback function is invoked, it is passed three arguments as described below.

resy_callb
Must be a pointer to a function that processes i_am_back packets as they are received from the xmservd daemon. When this callback function is invoked it is passed three arguments as described below.

excp_callb
Must be NULL or a pointer to a function that processes except_rec packets as they are received from the xmservd daemon. If a NULL pointer is passed, your application does not receive except_rec messages. When this callback function is invoked, it is passed three arguments as described below. This argument always overrides the corresponding argument of any previous RSiInvite or RSiOpen subroutine call and can itself be overridden by subsequent executions of either. In this way, your application can turn exception monitoring on and off. For an RSiOpen call to override the exception processing specified by a previous open call, the connection must first be closed with the RSiClose subroutine call.

The feed_callb, resy_callb, and excp_callb functions are called with the arguments:

RSiHandle. When a data_feed packet is received, the structure pointed to is guaranteed to represent the host sending the packet. In all other situations the RSiHandle structure may represent any of the hosts to which your application is talking.

Pointer of type pack * to the input buffer containing the received packet. In callback functions, always use this pointer rather than the pointer in the RSiHandle structure.

Pointer of type struct sockaddr_in * to the Internet address of the originating host.

Return Values

If successful, the subroutine returns zero and initializes the array element of type RSiHandle pointed to by rhandle. If an error occurs, error text is placed in the external character array RSiEMsg and the subroutine returns a negative value.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiClose subroutine , RSiInvite subroutine , RSiOpen subroutine .


RSiPathAddSetStat Subroutine

Purpose

Add a single statistics value to an already defined SpmiStatSet.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
struct SpmiStatVals *RSiPathAddSetStat(rhandle, statset, 
path)
RSiHandle rhandle;
struct SpmiStatSet *statset;
char *path;

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

statset
Must be a pointer to a structure of type struct SpmiStatSet, which was previously returned by a successful RSiCreateStatSet subroutine call.

path
Must be the full value path name of the statistics value to add to the SpmiStatSet. The value path name must not include a terminating slash. Note that value path names never start with a slash.

Return Values

If successful, the subroutine returns a pointer to a structure of type struct SpmiStatVals. 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 RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateStatSet subroutine , RSiOpen subroutine .


RSiPathGetCx Subroutine

Purpose

Searches the context hierarchy for an SpmiCx context that matches a context path name.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
cx_handle *RSiPathGetCx(rhandle, path)
RSiHandle rhandle;
char *path;

Description

The RSiPathGetCx subroutine performs the following actions:

  1. Searches the context hierarchy for a given path name of a context.
  2. Returns a handle to be used when subsequently referencing the context.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

path
A path name of a context for which a handle is to be returned. The context path name must be the full path name and must not include a terminating slash. Note that context path names never start with a slash.

Return Values

If successful, the subroutine returns a handle defined as a pointer to a structure of type cx_handle. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiFirstCx subroutine , RSiOpen subroutine , RSiNextCx subroutine .


RSiStatGetPath Subroutine

Purpose

Finds the full path name of a statistic identified by a SpmiStatVals pointer.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
char *RSiStatGetPath(rhandle, svp)
RSiHandle rhandle;
struct SpmiStatVals *svp;

Description

The RSiStatGetPath subroutine performs the following:

  1. Validates that the SpmiStatVals statistic identified by the second argument does exist.
  2. Returns a pointer to a character array containing the full value path name of the statistic.

The memory area pointed to by the returned pointer is freed when the RSiStatGetPath subroutine call is repeated. For each invocation of the subroutine, a new memory area is allocated and its address returned.

If the calling program needs the returned character string after issuing the RSiStatGetPath subroutine call, the program must copy the returned string to locally allocated memory before reissuing the subroutine call.

Parameters

rhandle
Must be an RSiHandle, previously initialized by the RSiOpen subroutine.

svp
Must be a handle of type struct SpmiStatVals as returned by a successful RSiPathAddSetStat subroutine call.

Return Values

If successful, the RSiStatGetPath subroutine returns a pointer to a character array containing the full path name of the statistic. If unsuccessful, the subroutine returns a NULL value and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiPathAddSetStat subroutine .


RSiStartFeed Subroutine

Purpose

Tells xmservd to start sending data feeds for a statset.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiStartFeed(rhandle, statset, msecs)
RSiHandle rhandle;
struct SpmiStatSet *statset;
int msecs;

Description

The RSiStartFeed subroutine performs the following function:

  1. Informs xmservd of the frequency with which it is required to send data_feed packets.
  2. Tells the xmservd to start sending data_feed packets.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

statset
Must be a pointer to a structure of type struct SpmiStatSet, which was previously returned by a successful RSiCreateStatSet subroutine call.

msecs
The number of milliseconds between the sending of data_feed packets. This number is rounded to a multiple of min_remote_int milliseconds by the xmservd daemon on the remote host. This minimum interval can be modified through the -i command line interval to xmservd.

Return Values

If successful, the subroutine returns zero; otherwise it returns -1 and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateStatSet subroutine , RSiOpen subroutine , RSiStopFeed subroutine .


RSiStartHotFeed Subroutine

Purpose

Tells xmservd to start sending hot feeds for a hotset or to start checking for if exceptions or SNMP traps should be generated.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiStartFeed(rhandle, hotset, msecs)
RSiHandle rhandle;
struct SpmiHotSet *hotset;
int msecs;

Description

The RSiStartHotFeed subroutine performs the following function:

  1. Informs xmservd of the frequency with which it is required to send hot_feed packets, if the hotset is defined to generate hot_feed packets.
  2. Informs xmservd of the frequency with which it is required to check if exceptions or SNMP traps should be generated. This is only done if it is specified for the hotset that exceptions and/or SNMP traps should be generated.
  3. Tells the xmservd to start sending data_feed packets and/or start checking for exceptions or traps.

Parameters

rhandle
Must be an RSiHandle, which was previously initialized by the RSiOpen subroutine.

hotset
Must be a pointer to a structure of type struc SpmiHotSet, which was previously returned by a successful RSiCreateHot subroutine call.

msecs
The number of milliseconds between the sending of hot_feed packets and/or the number of milliseconds between checks for if exceptions or SNMP traps should be generated. This number is rounded to a multiple of min_remote_int milliseconds by the xmservd daemon on the remote host. This minimum interval can be modified through the -i command line interval to xmservd.

Return Values

If successful, the subroutine returns zero; otherwise it returns -1 and an error text may be placed in the external character array RSiEMsg.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiCreateHotSet subroutine , RSiOpensubroutine , RsiChangeHotFeed subroutine , RSiStopHotFeed subroutine .


RSiStopFeed Subroutine

Purpose

Tells xmservd to stop sending data feeds for a statset.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiStopFeed(rhandle, statset, erase)
RSiHandle rhandle;
struct SpmiStatSet *statset;
boolean erase;

Description

The RSiStopFeed subroutine instructs the xmservd of a remote system to:

  1. Stop sending data_feed packets for a given SpmiStatSet . If the daemon is not told to erase the SpmiStatSet, feeding of data can be resumed by issuing the RSiStartFeed subroutine call for the SpmiStatSet.
  2. Optionally tells the daemon and the API library subroutines to erase all their information about the SpmiStatSet. Subsequent references to the erased SpmiStatSet are invalid.

Parameters

rhandle
Must point to a structure of type RSiHandle, which was previously initialized by the RSiOpen subroutine.

statset
Must be a pointer to a structure of type struct SpmiStatSet, which was previously returned by a successful RSiCreateStatSet subroutine call. Data feeding must have been started for this SpmiStatSet via a previous RSiStartFeed subroutine call.

erase
If this argument is set to true, the xmservd daemon on the remote host discards all information about the named SpmiStatSet. Otherwise the daemon maintains its definition of the set of statistics.

Return Values

If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiStartFeed subroutine .


RSiStopHotFeed Subroutine

Purpose

Tells xmservd to stop sending hot feeds for a hotset and to stop checking for exception and SNMP trap generation.

Library

RSI Library (libSpmi.a)

Syntax

#include <sys/Rsi.h>
int RSiStopFeed(rhandle, hotset, erase)
RSiHandle rhandle;
struct SpmiHotSet *hotset;
boolean erase;

Description

The RSiStopHotFeed subroutine instructs the xmservd of a remote system to:

  1. Stop sending hot_feed packets or check if exceptions or SNMP traps should be generated for a given SpmiHotSet. If the daemon is not told to erase the SpmiHotSet, feeding of data can be resumed by issuing the RSiStartHotFeed subroutine call for the SpmiHotSet.
  2. Optionally tells the daemon and the API library subroutines to erase all their information about the SpmiHotSet. Subsequent references to the erased SpmiHotSet are invalid.

Parameters

rhandle
Must point to a structure of type RSiHandle, which was previously initialized by the RSiOpen subroutine.

hotset
Must be a pointer to a structure of type struct SpmiHotSet, which was previously returned by a successful RSiCreateHotSet subroutine call. Data feeding must have been started for this SpmiStatSet via a previous RSiStartHotFeed subroutine call.

erase
If this argument is set to true, the xmservd daemon on the remote host discards all information about the named SpmiHotSet. Otherwise the daemon maintains its definition of the set of statistics.

Return Values

If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.

Error Codes

All RSI 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 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. RSi error codes are described in List of RSi Error Codes .

Implementation Specifics

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

Files

/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI.

Related Information

RSiOpen subroutine , RSiStartHotFeed subroutine , RSiChangeHotFeed subroutine .


List of RSi Error Codes

All RSI subroutines use constants to define error codes. The RSI Error Code table lists the error descriptions.

Symbolic Name Number Description
RSiTimeout 280 A time-out occurred while waiting for a response to a request.
RSiBusy 281 An RSiOpen subroutine was issued, but another is already active.
RSiSendErr 282 An error occurred when the library attempted to send a UDP packet with the sendto() system call.
RSiPollErr 283 A system error occurred while issuing or processing a poll() or select() system call.
RSiRecvErr 284 A system error occurred while attempting to read an incoming UDP packet with the recvfrom() syatem call.
RSiSizeErr 285 A recvfrom() system call returned a UDP packet with incorrect length or incorrect source address.
RSiResync 286 While waiting for a response to an outgoing request, one of the following occurred and cause an error return to the calling program:
  1. An error occurred while processing an exception packet.
  2. An error occurred while processing an i_am_back packet.
  3. An i_am_back packet was received in response to an output request other than are_you_there.
  4. While waiting for a respose to an outgoing request, some asynchronous function closed the handle for the remote host.

The code may also be set when a success return code ia returned to the caller, in which case it shows that either an exception packet or an i_am_back packet was processed successfully while waiting for a response.

RSiBadStat 287 A bad status code was received in the data packet received.
RSiBadArg 288 An invalid argument was passed to an RSi subroutine.
RSiBadHost 289 A valid host address can not be constructed from an IP address or the nameservice doesn't know the hostname.
RSiDupHost 290 An RSiOpen call was issued against a host but a connection is already open to a host with this IP address and a different hostname.
RSiSockErr 291 An error occurred while opening or communicating with a socket.
RSiNoPort 292 The RSi is unable to find the port number to use when inviting remote suppliers. The likely cause is that the xmquery entry is missing from the /etc/services file or the NIS (Yellow Pages) server.
RSiNoMatch 293 One of the following occurred:
  1. The SpmiStatVals argument on the RSiStatGetPath call is invalid.
  2. On an RSiPathAddSetStat call, the SpmiStatSet argument is invalid or the path name given in the last argument does not exist.
  3. On an RSiAddSetHot call, the SpmiHotSet argument is invalid, the grand parent context doesn't exist or none of its subcontexts contain the specified statistic.
  4. On an RSiDelSetStat call, the SpmiStatSet or the SpmiStatVals argument is invalid.
  5. On an RSiDelSetHot call, the SpmiHotSet or the SpmiHotVals argument is invalid.
  6. On an RSiPathGetCx call, the path name given does not exist.
  7. On an RSiGetValue or RSiGetRawValue call, the SpmiStatVals argument is invalid
  8. On an RSiGetHotItem call, the SpmiHotSet argument was invalid.
RSiInstErr 294 An error was returned when attempting to instantiate a remote context.
RSiNoFeed 295 When extracting a data value with the RSiGetValue call, the data value was marked as invalid by the remote data supplier.
RSiTooMany 296 An attempt was made to add more values to a statset than the current buffer size permits.
RSiNoMem 297 Memory allocation error.
RSiNotInit 298 An RSi call was attempted before an RSiInit call was issued.
RSiNoLicense 299 License expired or no license found.
RSiNotSupported 300 The subroutine call requires a later protocol version that the one supported by the remote system's xmservd.

[ Previous | Next | Contents | Glossary | Search ]