Purpose
ha_gs_init - Called by a process to register with the Group Services Application Programming Interface (GSAPI)
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_init(
ha_gs_descriptor_t *ha_gs_descriptor,
const ha_gs_socket_ctrl_t socket_options,
const ha_gs_responsiveness_t *responsiveness_control,
const char *deactivate_script,
ha_gs_responsiveness_cb_t *responsiveness_callback,
ha_gs_delayed_error_cb_t *delayed_error_callback,
ha_gs_query_cb_t *query_callback)
Parameters
The process itself must not read or write directly on this file descriptor.
Description
The ha_gs_init subroutine is used by a process to register itself with the Group Services Application Programming Interface (GSAPI). The subroutine allows the GSAPI to initialize itself as necessary and establishes a connection between the GSAPI and the GS client. This subroutine returns synchronously.
Only processes that meet one of the following conditions are allowed to initialize themselves with the GSAPI:
Refer to PSSP: Administration Guide, SA22-7348 for information about setting up the Group Services subsystem to enable support for use of hagsuser.
As described in Group Services domains, a GS client must indicate the Group Services domain to which it wants to attach by setting the following environment variables prior to invoking ha_gs_init. This domain may be the Group Services PSSP domain. It may also be a Group Services HACMP/ES domain if HACMP/ES is installed, or it may be the RSCT domain.
The HA_DOMAIN_NAME environment variable must be set and exported in a GS client's environment to the name of the domain in which the GS client and the Group Services daemon are running. On a node, this is the domain to which the node belongs. On the control workstation, there is a Group Services daemon for each domain, and the setting of HA_DOMAIN_NAME identifies the domain and the particular Group Services daemon to which the GS client will connect.
The responsiveness control structure has the following definition:
typedef struct
{
ha_gs_responsiveness_type_t gs_responsiveness_type;
unsigned int gs_responsiveness_interval;
ha_gs_time_limit_t gs_responsiveness_response_time_limit;
void *gs_counter_location;
unsigned int gs_counter_length;
} ha_gs_responsiveness_t; /* responsiveness attributes */
The responsiveness control structure is used to specify whether the process wants the GSAPI to check it periodically for responsiveness and, if so, the protocol to be used. It should be noted that the GSAPI will always be able to detect the actual exit (intentional or otherwise) of all GS clients. However, this check allows the GSAPI to determine if the GS client is able to respond in a reasonable fashion. It also allows the GS client to perform any periodic validity checks on its own operation or environment that might be needed.
If the GS client fails a responsiveness check and it is joined to any groups as a provider, the other providers in the groups receive an announcement that a provider has failed its responsiveness protocol.
The responsiveness protocol is run only when the GS client is idle. If the GS client is involved in group actions (for example, running protocols) and it is responding as expected, the GSAPI does not perform the responsiveness protocol.
The gs_responsiveness_type field contains the type of responsiveness protocol that is to be performed for this GS client. It may take one of the following values:
The gs_responsiveness_interval field contains the number of seconds that the GSAPI should wait between invocations of the specified responsiveness protocol.
The gs_responsiveness_response_time_limit field contains the number of seconds that the GSAPI should wait for a return from the responsiveness callback routine. If the routine fails to return, the GSAPI assumes that the GS client has become nonresponsive.
The gs_counter_location field points to the counter that the GSAPI should monitor for the HA_GS_COUNTER_RESPONSIVENESS protocol. The counter must reside in the GS client's address space. If the HA_GS_PING_RESPONSIVENESS protocol is specified, this field is ignored.
The gs_counter_length field contains the length in bytes, of the counter to be monitored. It may be a value of 2, 4, or 8. If the HA_GS_PING_RESPONSIVENESS protocol is specified, this field is ignored.
Security
The effective user ID of the calling process must be root, the effective user ID must be a supplementary user ID to an AIX group called hagsuser, or the effective group ID must be an AIX group called hagsuser.
Return Values
If the ha_gs_init subroutine is successful, it returns a value of 0 (HA_GS_OK), and the ha_gs_descriptor field contains the file descriptor of the GSAPI socket.
Error Values
If the ha_gs_init subroutine is unsuccessful, it returns an error number synchronously. The contents of the ha_gs_descriptor field are undefined.
If the calling process fails to connect the Group Services subsystem because of insufficient authority, the ha_gs_init subroutine may be successful, but ha_gs_dispatch returns an error synchronously.
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_init subroutine:
Asynchronous Errors
None.
Files
ha_gs.h
Prerequisite Information
Related Information
Structures in the ha_gs.h header file: ha_gs_responsiveness_t type definition
Subroutines: ha_gs_init, ha_gs_join, ha_gs_send_message, ha_gs_leave, ha_gs_expel, ha_gs_subscribe, ha_gs_change_attributes, ha_gs_change_state_value, ha_gs_goodbye, ha_gs_get_adapter_info, ha_gs_get_node_number.