IBM Books

Group Services Programming Guide and Reference

ha_gs_expel subroutine

Purpose

ha_gs_expel - Called by a provider of a group to request the expulsion of one or more providers.

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_expel(
                ha_gs_token_t           provider_token,
        const   ha_gs_proposal_info_t   *proposal_info)
 

Parameters

provider_token
A token that identifies the caller as a provider of the group. This token was previously initialized when the provider joined the group by using the ha_gs_join subroutine.

proposal_info
A pointer to a buffer that contains a proposal information block, which describes the proposed expel request.

Description

The ha_gs_expel subroutine is used by a provider of a Group Services group to propose the expulsion of one or more providers. A provider may propose the expulsion of itself.

A group might decide that a provider should be expelled for a number of reasons. Examples include:

If the request is specified as a one-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal protocol approval procedures.

If the request is specified as an n-phase protocol, and Group Services chooses to run this protocol, the group's providers are notified using normal n-phase voting procedures.

If the Group Services subsystem chooses not to run this protocol (because another protocol is already in progress), the HA_GS_COLLIDE error number is returned either synchronously or asynchronously, depending on when the error is detected. Asynchronous errors are delivered through the delayed error callback routine. Otherwise, the proposal will initiate a protocol within the group.

Information about the expel request is supplied through the expel request block, which is a type of proposal information block. On the ha_gs_expel subroutine, specify the proposal information block as an expel request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.

The expel request block has the following definition:

typedef struct {
    ha_gs_num_phases_t      gs_num_phases;
    ha_gs_time_limit_t      gs_time_limit;
    ha_gs_membership_t      gs_expel_list;
    unsigned int            gs_deactivate_phase;
    char                    *gs_deactivate_flag;
} ha_gs_expel_request_t;

The gs_num_phases field specifies whether the expel protocols are to be n-phase protocols or one-phase protocols. It can take one of the following values:

HA_GS_1_PHASE
The protocols are to be one-phase protocols. One-phase protocols are automatically approved.

HA_GS_N_PHASE
The protocols are to be n-phase protocols, which put the group into multi-phase voting.

The gs_time_limit field contains the voting phase time limit, in seconds.

For providers that are not being expelled, this is the number of seconds within which each provider must register its vote for each phase of an n-phase protocol. If the field is set to a value of 0, no limit is enforced.

For providers that are being expelled, this is the number of seconds within which the deactivate script must complete. Otherwise, the deactivate script is considered unsuccessful. The deactivate script that is invoked is the one that was specified on the ha_gs_init subroutine when the provider that is being expelled first registered with Group Services.

The gs_expel_list field is a list of providers that are targeted to be expelled. It has the following definition:

typedef struct {
    unsigned int        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.

The providers in the expel list do not take part in the protocol and receive no notice of it, unless it is approved.

All of the providers that are not targeted for expulsion take part in the protocol, even if they were declared nonresponsive before the protocol began.

The gs_deactivate_phase field contains the phase number in which the deactivate script should be run against the providers that are being expelled. If this field contains 0, no deactivate script will be invoked.

The gs_deactivate_flag field contains a flag that is to be passed to the deactivate script. It is a pointer to a null-terminated string with a maximum length of 256 bytes. If you specify a string that is longer than 256 bytes, it will be truncated. If the pointer is null, no flag will be passed to the deactivate script.

Deactivate Scripts

For information about deactivate scripts, see Deactivate scripts.

Restrictions

The calling process must be a provider. The group must not already be running an n-phase protocol.

Return Values

If the ha_gs_expel subroutine is successful, it returns a value of 0 (HA_GS_OK). Group Services has accepted the request and will asynchronously attempt to run the proposed protocol.

Error Values

If the ha_gs_expel subroutine is unsuccessful, it returns an error number. 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).

Asynchronous Errors

The following errors may be returned asynchronously by the ha_gs_expel subroutine:

HA_GS_NOT_A_MEMBER
The provider that is proposing the protocol is no longer a provider for the specified group.

HA_GS_BAD_PARAMETER
The specified parameter was not valid.

HA_GS_COLLIDE
Another protocol is already active for this group.

HA_GS_UNKNOWN_PROVIDER
At least one of the providers that was specified in an expel protocol is not a member of the specified group.

Synchronous Errors

The following errors may be returned synchronously by the ha_gs_expel subroutine:

HA_GS_BAD_MEMBER_TOKEN
The given provider_token does not specify a valid provider joined to a group.

HA_GS_BAD_PARAMETER
The number of phases specified for the protocol is not allowable (it must be HA_GS_1_PHASE or HA_GS_N_PHASE); or no providers were specified to be expelled.

HA_GS_COLLIDE
The provider's group is already running a protocol, or this provider has already submitted a protocol request.

HA_GS_INVALID_DEACTIVATE_PHASE
The specified gs_deactivate_phase is less than zero; or the protocol is specified as a one phase (gs_num_phases is HA_GS_1_PHASE) and gs_deactivate_phase is greater than one.

HA_GS_NO_INIT
The GS client has not yet successfully initialized itself with Group Services by calling ha_gs_init().

HA_GS_NOT_A_MEMBER
The given provider_token does not specify a valid group.

HA_GS_NOT_OK
The connection to the GS daemon has been lost. The GS client needs to reinitialize (via ha_gs_init()).

HA_GS_NOT_SUPPORTED
The GS client was not compiled against the proper level of the GS library to use this function.

HA_GS_PROVIDER_APPEARS_TWICE
A provider to be expelled is listed twice in the given gs_expel_list.

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_subscribe, ha_gs_change_attributes, ha_gs_goodbye


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]