Invites data suppliers on the network to identify themselves and returns a table of data-supplier host names.
RSI Library (libSpmi.a)
#include sys/Rsi.h
char **RSiInvite(resy_callb, excp_callb) int (*resy_callb)(); int (*excp_callb)();
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.
The arguments to the subroutine are:
resy_callbMust 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_callbMust 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:
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.
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.
This subroutine is part of the Performance Toolbox for AIX licensed product.
| /usr/include/sys/Rsi.h | Declares the subroutines, data structures, handles, and macros that an application program can use to access the RSI. |
For related information, seeRSiOpen Subroutine.