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.

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

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

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

This argument always overrides the corresponding argument of any previous RSiInvite or RSiOpen call, and it can 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:

• An RSiHandle. The RSi handle pointed to is almost certain not to represent the host that sent the packet. Ignore this argument, and use only the second one: the pointer to the input buffer.
• A pointer of type pack * to the input buffer containing the received packet. Always use this pointer rather than the pointer in the RSiHandle structure.
• A pointer of type struct sockaddr_in * to the IP address of the originating host.

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 IP address. The two “words” are separated by one or more blanks. This format is suitable as an argument to the RSiOpen (RSiOpen Subroutine) 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 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