Purpose
ha_gs_subscribe - Called by a GS client to join a group as a subscriber
Library
GSAPI Thread-Safe Library (libha_gs_r.a)
GSAPI Library (not thread-safe) (libha_gs.a)
Syntax
#include <ha_gs.h>
ha_gs_rc_t
ha_gs_subscribe(
ha_gs_token_t *subscriber_token,
const ha_gs_proposal_info_t *proposal_info)
Parameters
The ha_gs_subscribe subroutine is used by a GS client to register as a subscriber for a Group Services group. If the named group does not already exist, the HA_GS_UNKNOWN_GROUP error number is returned asynchronously by the delayed error callback routine.
Note that subscribers are known only to the Group Services subsystem. The providers of the group and the other subscribers of the group are unaware of any of the subscribers to the group.
In addition to groups defined by providers, a GS client can subscribe to a number of system-defined groups. These provide status information about nodes and various communications adapters. A listing of these groups appears later in this section. Additional information about these concepts is in the section Host and adapter membership groups.
Information about the subscribe request is supplied through the subscribe request block, which is a type of proposal information block. On the ha_gs_subscribe subroutine, specify the proposal information block as a subscribe request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.
The subscribe request block has the following definition:
typedef struct {
ha_gs_subscription_ctrl_t gs_subscription_control;
ha_gs_group_name_t gs_subscription_group;
ha_gs_subscriber_cb_t *gs_subscription_callback;
} ha_gs_subscribe_request_t;
The gs_subscription_control field contains one or more flags that indicate the types of information that the subscriber wishes to receive about changes to the subscribed-to group. A GS client may subscribe to changes in the group's state, its membership list, or both.
The flags are not exclusive and may be specified in any combination by OR'ing the individual flags together. The flags that may be specified are:
If HA_GS_SUBSCRIBE_MEMBERSHIP is not specified, but at least one of the delta flags is specified, the subscriber still receives the full list of providers in the group on the first subscription notification that contains membership data for the group. Subsequent notifications contain only the delta list of joining or leaving providers.
The gs_subscription_group field points to a string that contains the name of the group to which the caller wishes to subscribe.
The gs_subscription_callback field points to the callback routine that is to be called when Group Services has a notification to deliver that contains data that satisfies this subscription request. A pointer to a valid function must be given in the gs_subscription_callback field. If a NULL pointer is given, a synchronous error of HA_GS_BAD_PARAMETER will be returned on the call to ha_gs_subscribe. If the pointer is not NULL but does not point to an executable function, then unpredictable results, such as fatal program failure, may occur during execution of your program.
A process can also subscribe for host or adapter membership information as follows.
These groups are specified for subscription by using the following constants:
If the SP system on which the GS client is running does not have an SP Switch, or it is not currently active on any nodes, a request to subscribe to HA_GS_CSS0_MEMBERSHIP_GROUP or HA_GS_CSS1_MEMBERSHIP_GROUP will result in an asynchronous HA_GS_UNKNOWN_GROUP delayed error.
If the node on which the GS client is running does not have an active SP Switch adapter, then a request to subscribe to HA_GS_CSSRAW_MEMBERSHIP_GROUP will result in an asynchronous HA_GS_UNKNOWN_GROUP delayed error. It is also possible to receive subscription "special" data on notifications for this group. (See Appendix A, Subscription special data.)
If a GS client is running in the Group Services PSSP domain and attempts to subscribe to one of the Group Services HACMP/ES domain system-defined groups, it will result in an asynchronous HA_GS_UNKNOWN_GROUP delayed error.
The availability of information from the adapter membership groups supported within the HACMP/ES Group Services domain depends upon the set of networks defined to HACMP/ES for heartbeating. You can specify any of the above-mentioned groups; however, the GS client will receive an asynchronous HA_GS_UNKNOWN_GROUP delayed error in the following cases:
In any case where the GS client receives an asynchronous delayed error on a subscription request, it may want to wait a period of time and reissue the request, as adapters may have become active in the interim.
For all subscriptions to system-defined groups, all controls and notifications act very much like those for subscriptions to user-defined groups. The subscription control flags in the gs_subscription_control field may be used to control the level of information received by the subscriber for the host or adapter membership group notifications.
Notifications for host or adapter membership look the same as notifications for any other group; each active node or adapter is represented as a provider. The instance number for each node "provider" is a value of 0 and the node number for each node "provider" is its node number. The instance number for each adapter "provider" is its adapter interface number (for example, a value of 2 for en2) and the node number for each adapter "provider" is the node on which it is installed.
Nodes and adapters are ordered from "oldest" to "youngest," The oldest node or adapter (that is, the first node or adapter to join its membership group) is at the head of the list and the youngest is at the end.
Restrictions
The calling process must be a GS client.
Return Values
If the ha_gs_subscribe subroutine is successful, it returns a value of 0 (HA_GS_OK) and the subscriber_token field is set to the token that identifies this subscriber's connection to the group.
Note that subscriber tokens are assigned, invalidated, and reassigned in a manner similar to the way in which file descriptors are assigned, invalidated, and reassigned as files are opened and closed.
Here is an example.
A GS client subscribes to group bar and receives subscriber token 2. When the same client unsubscribes from group bar or becomes unsubscribed because group bar is dissolved, Group Services invalidates subscriber token 2 and makes it available for reassignment. When the next GS client (it could be the same or a different GS client) subscribes to the next group (it could be the same or a different group), Group Services assigns subscriber token 2 to that client.
Error Values
If the ha_gs_subscribe subroutine is unsuccessful, it returns an error number and the contents of the subscriber_token field are undefined. If the error is detected immediately, an error is returned synchronously. If the error is detected after the call has been accepted, an error is returned asynchronously.
The GSAPI error numbers are defined in the ha_gs.h header file. For more information on GSAPI errors, see GSAPI errors (err_gsapi).
Synchronous Errors
The following errors may be returned synchronously by the ha_gs_subscribe subroutine:
Asynchronous Errors
The following errors may be returned asynchronously by the ha_gs_subscribe subroutine:
Files
ha_gs.h
Prerequisite Information
Related Information
Subroutines: ha_gs_init, ha_gs_unsubscribe