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:

• Allocate an array of RSiHandleStruct structures and return the address of the array to the data-consumer program.
• Increase the size of a previously allocated array of RSiHandleStruct structures and initialize the new array with the contents of the previous one.

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

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. 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 Remote Statistic Interface (RSI) subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:

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

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

Files