scds_svc_wait(3HA)					 Sun Cluster HA and Data Services					scds_svc_wait(3HA)

NAME

       scds_svc_wait - wait for the specified timeout period for a monitored process to die

SYNOPSIS

       cc [flags...] -I /usr/cluster/include file -L /usr/cluster/lib  -l  dsdev
       #include <rgm/libdsdev.h>

       scha_err_t scds_svc_wait(scds_handle_t handle, time_t timeout

DESCRIPTION

       The  scds_svc_wait() function waits for the specified timeout period for a monitored process group to die. It waits upon all process groups
       started by scds_pmf_start(3HA) for the resource passed to the calling START method.  The scds_svc_wait() function uses  the  Retry_interval
       and  Retry_count  properties  of  the  resource	to  limit  the number of process deaths to wait on. If the number of process deaths during
       Retry_interval reaches the value of Retry_count, scds_svc_wait() returns with SCHA_ERR_FAIL.

       If the number of process failures is below the value of Retry_count, the process is restarted and scds_svc_wait() waits	the  full  timeout
       period for further process deaths. The counting of process failures spans successive calls to scds_svc_wait().

PARAMETERS

       The following parameters are supported:

       handle		   The handle returned from scds_initialize(3HA)

       timeout		   Timeout period measured in seconds

RETURN VALUES

       The scds_svc_wait() function returns the following:

       0		   The function succeeded.

       non-zero 	   The function failed.

ERRORS

       SCHA_ERR_TIMEOUT 	   The function timed out.

       SCHA_ERR_NOERR		   No process deaths occurred, or a process was successfully restarted.

       SCHA_ERR_FAIL		   The number of failures reached the value of the Retry_count property.

       SCHA_ERR_STATE		   A system error or an otherwise unexpected error occurred.

       See  scha_calls(3HA) for a description of other error codes.

EXAMPLES

       Example 1 Using scds_svc_wait() in a START Method

       The following example shows how you could use scds_svc_wait in a START method to return early if the service fails to start. After starting
       an application process with scds_pmf_start(), a START method must wait for the application to fully initialize itself and become  available
       before  returning  success.  If the application fails to start, the START method must wait the entire Start_timeout period before returning
       with failure. Using scds_svc_wait(), as in the following example, allows START methods to restart applications up to Retry_count times  and
       return early with failure from the START method if the service is unable to start up.

	 /*
	 * scds_svc_wait is a subroutine in a START method to
	 * check that the service is fully available before returning.
	 * Calls svc_probe() to check service availability.
	 */
	 int
	 svc_wait(scds_handle_t handle)
	 {
	      while(1) {
		   /* Wait for 5 seconds */
		   if (scds_svc_wait(handle, 5) != SCHA_ERR_NOERR) {
			scds_syslog(LOG_ERR, "Service failed to start.");
			return(1);	    /* Start Failure */
		   }
		   /* Check if service is fully up every 5 seconds */
		   if (svc_probe(handle) == 0) {
			scds_syslog(LOG_INFO, "Service started successfully.");
			return(0);
		   }
	      }
	      return(0);
	 }

FILES

       /usr/cluster/include/rgm/libdsdev.h

	   Include file

       /usr/cluster/lib/libdsdev.so

	   Library

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWscdev 		   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       scds_initialize(3HA), scds_pmf_start(3HA) , scha_calls(3HA), attributes(5), r_properties(5)

NOTES

	   o	  If  the  START  method  exceeds  the Start_timeout setting on the resource, the RGM will kill the START method even if the START
		  method is currently waiting for scds_svc_wait() to return.

	   o	  If Retry_interval on the resource is larger then Start_timeout, the START method could be timed out by the RGM even if the  num-
		  ber of failures is below Retry_count.

	   o	  If  a START method starts multiple process groups with multiple calls to scds_pmf_start(), scds_svc_wait() starts process groups
		  as they die. It does not enforce any dependencies between process groups. Do not use scds_svc_wait() if there  is  a	dependency
		  between  process  groups such that failure of one process group requires a restart of other process groups. Instead, use sleep()
		  to wait between health checks of the process groups.

Sun Cluster 3.2 						    7 Sep 2007							scds_svc_wait(3HA)