Purpose
ha_gs_change_attributes - Called by a provider of a group to propose a change to the group's attributes
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_change_attributes(
ha_gs_token_t provider_token,
const ha_gs_proposal_info_t *proposal_info)
Parameters
Description
The ha_gs_change_attributes subroutine is used by a provider of a Group Services group to propose a change to the group's attribute value.
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 attribute change request is supplied through the attribute change request block, which is a type of proposal information block. On the ha_gs_change_attributes subroutine, specify the proposal information block as an attribute change request block. For the definition of the proposal information block, see the ha_gs_delayed_error_callback man page.
The change attributes 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_group_attributes_t *gs_group_attributes;
ha_gs_membership_t *gs_backlevel_providers;
} ha_gs_change_attributes_t;
The gs_num_phases field specifies whether the attribute change protocols are to be n-phase protocols or one-phase protocols. It can take one of the following values:
The gs_time_limit field contains the voting phase time limit, in seconds. 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 has a value of 0, no limit is enforced.
The group attributes block describes the attributes of the group, including the group's name. The group attribute block is specified as input to a change attribute request using the ha_gs_change_attribute subroutine. It has the following definition:
typedef char *ha_gs_group_name_t;
typedef struct {
short gs_version;
short gs_sizeof_group_attributes;
unsigned gs_client_version;
ha_gs_group_name_t gs_group_name;
ha_gs_batch_ctrl_t gs_batch_control;
ha_gs_num_phases_t gs_num_phases;
ha_gs_num_phases_t gs_source_reflection_num_phases;
ha_gs_vote_value_t gs_group_default_vote;
ha_gs_merge_ctrl_t gs_merge_control;
ha_gs_time_limit_t gs_time_limit;
ha_gs_time_limit_t gs_source_reflection_time_limit;
ha_gs_group_name_t gs_source_group_name;
} ha_gs_group_attributes_t;
The group attributes block contains the name of the group and the set of group attributes that are passed to the Group Services subsystem on the ha_gs_change_attributes subroutine call.
The ha_gs_change_attributes subroutine can change the following attributes:
For attribute descriptions, see the complete list of group attributes under the ha_gs_join Subroutine.
The gs_backlevel_providers field in the change attributes request block should be set to NULL when it is submitted to the ha_gs_change_attributes subroutine.
If the request is returned with an asynchronous error of HA_GS_BACKLEVEL_PROVIDERS, the gs_backlevel_providers field will point to a list of providers. These providers are in the group that was compiled and linked against a version of PSSP earlier than 3.1 (for RS/6000 SP systems) or against a version of HACMP/ES earlier than HACMP 4.3 (for RS/6000 workstation clusters). In this case, the request will be returned asynchronously via the ha_gs_delayed_error_callback function.
For the group to successfully use the ha_gs_change_attributes subroutine to dynamically change the group's attributes, all providers in the group must be compiled (or recompiled) against the proper level of the Group Services subsystem library, as described above.
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_change_attributes 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_change_attributes 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).
Synchronous Errors
The following errors may be returned synchronously by the ha_gs_change_attributes subroutine:
Asynchronous Errors
The following errors may be returned asynchronously by the ha_gs_change_attributes subroutine:
One or more providers in the group were compiled and linked against a version of PSSP earlier than PSSP 3.1 (for RS/6000 SP systems) or a version of HACMP/ES earlier than HACMP 4.3 (for RS/6000 workstation clusters). This error code is sent with a delayed-error notification to the provider proposing to change the attributes. The delayed-error notification contains a list of the back-level providers, to identify which processes need to be upgraded.
In this case, to change the attributes for a group, all providers must leave the group and rejoin with the new attributes.
Another protocol is already active for this group. In this case, to change the attributes for a group, the provider must resubmit the request.
The Group Services subsystem on one or more machines in the domain does not support the appropriate functionality. This error code is sent with a delayed-error notification to the provider proposing to change the group attributes.
In this case, to change the attributes for a group, all providers must leave the group and rejoin with the new attributes.
Files
ha_gs.h
Prerequisite Information
Related Information
Subroutines: ha_gs_init, ha_gs_join, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_subscribe, ha_gs_change_state_value, ha_gs_goodbye