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.

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

Parameters

The arguments to the subroutine are:

rhandle

Must point to an element of the RSiHandleStruct array, which is returned by a previous RSiInit (RSiInit Subroutine) 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 because 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 is the one with which you want to talk. The first characters 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 in the following information.

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 in the following information.

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 in the following information. This argument always overrides the corresponding argument of any previous RSiInvite (RSiInvite Subroutine) or RSiOpen (RSiOpen Subroutine) 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 (RSiClose Subroutine) 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.
• 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 IP 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 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