Group Services Programming Guide and Reference

ha_gs_announcement_callback subroutine

Purpose

ha_gs_announcement_callback - A callback routine that the Group Services subsystem calls to deliver an announcement notification to a GS client

Library

GSAPI Thread-Safe Library (libha_gs_r.a)

GSAPI Library (not thread-safe) (libha_gs.a)

Syntax

#include <ha_gs.h>
 
void
    ha_gs_announcement_callback(
        const   ha_gs_announcement_notification_t       *notification)
 

Parameters

notification

A pointer to an announcement notification block.

Description

The ha_gs_announcement_callback subroutine defines a GS client's announcement callback routine. The GS client uses it to handle announcement notifications from the Group Services subsystem. The process provides the address of the announcement callback routine to the Group Services subsystem on the ha_gs_join subroutine when it joins the group as a provider. The Group Services subsystem then calls the announcement callback routine when it has an announcement notification to deliver to the GS client. Announcements provide detailed information about abnormal conditions, other than complete failure, that affect one or more providers in the group.

On input, the announcement callback routine receives a pointer to the announcement notification block. The announcement notification block has the following definition:

typedef struct {
    ha_gs_notification_type_t       gs_notification_type;
    ha_gs_token_t                   gs_provider_token;
    ha_gs_summary_code_t            gs_summary_code;
    ha_gs_membership_t              *gs_announcement;
} ha_gs_announcement_notification_t;

The gs_notification_type field contains the type of notification. For an announcement notification, it contains a value of HA_GS_ANNOUNCEMENT_NOTIFICATION.

The gs_provider_token field contains a token that identifies the caller as a provider of the group. This token was previously initialized when the provider joined the group using the ha_gs_join subroutine.

The gs_summary_code field contains one or more flags that indicate the type of announcement that is being delivered. It can contain one or more of the following flags:

HA_GS_TIME_LIMIT_EXCEEDED

This flag is set for an announcement notification when one or more providers failed to vote in time during a voting protocol. The gs_announcement field of the announcement notification block points to the list of providers that failed to vote in time.

HA_GS_RESPONSIVENESS_NO_RESPONSE

This flag is set for an announcement notification when one or more providers failed a responsiveness check. The gs_announcement field of the announcement notification block points to the list of providers that failed the responsiveness check.

HA_GS_RESPONSIVENESS_RESPONSE

This flag is set for an announcement notification when one or more providers that previously failed responsiveness checks are now responding successfully. The gs_announcement field of the announcement notification block points to the list of providers that are now responding successfully.

HA_GS_GROUP_DISSOLVED

This flag is reserved for IBM use.

HA_GS_GROUP_SERVICES_HAS_DIED_HORRIBLY

This flag is set for an announcement notification when the Group Services daemon has died.

The gs_announcement field points to a list of providers that are affected by the condition that is being reported by this announcement. It has the following definition:

typedef struct {
    ulong               gs_count;
    ha_gs_provider_t    *gs_providers;
} ha_gs_membership_t;

The gs_count field contains the number of providers in the list.

The gs_providers field points to the list of providers. Each provider is described by a provider information block, which is defined in the ha_gs_n_phase_callback man page.

Restrictions

For important information about multiprocessing considerations that apply to all callback routines, see the ha_gs_n_phase_callback man page.

Return Values

None.

Error Values

None.

Asynchronous Errors

None.

Files

ha_gs.h

Prerequisite Information

Understanding Group Services.

Related Information

Subroutines: ha_gs_init, ha_gs_join, ha_gs_change_state_value, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_change_attributes