RSiInvite or RSiInvitex 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)();

char **RSiInvitex(resy_callb, excp_callb)
int (*resy_callb)();
int (*excp_callb)();

Description

The RSiInvite or RSiInvitex 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 the i_am_back packets as they are received from the xmservd daemons on remote hosts for the duration of the RSiInvite, RSiInvitex 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, RSiInvitex 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 orRSiInvitex, RSiOpen or RSiOpenx 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 or RSiClosex call. That's because an RSiOpen or RSiOpenx call 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 or RSiHandlex. 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 or RSiHandlex structure.
• A pointer of type struct sockaddr_in * or struct sockaddr_in6 * 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 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 or RSiOpenx subroutine call. In addition, the external integer variable RSiInvTabActive or RSiInvTabActivex 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 must not assume that the pointer returned by this subroutine call remains valid after subsequent calls to RSiInvite or RSiInvitex. If the call is not successful, an error text is placed in the external RSiEMsg character array, an error number is placed in RSiErrno, and the subroutine returns NULL.

The list of host names returned by the RSiInvite or RSiInvitex does not include the hosts your program has already established a connection with through an RSiOpen or RSiOpenx 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 or RSiInvitex 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