PMRECONNECTCONTEXT(3)					     Library Functions Manual					     PMRECONNECTCONTEXT(3)

NAME

       pmReconnectContext - reconnect to a PMAPI context

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmReconnectContext(int handle);

       cc ... -lpcp

DESCRIPTION

       As  a  consequence  of  network,  host or Performance Metrics Collector Daemon (PMCD) failures, an applications connection to a PMCD may be
       established and then subsequently lost.

       The routine pmReconnectContext allows an application to request that the context identified by handle should  be  re-established,  provided
       the associated PMCD is accessible.

       To  avoid  flooding the system with reconnect requests, pmReconnectContext will only attempt a reconnection after a suitable delay from the
       previous unsuccessful attempt to reconnect this context. This imposed restriction on the reconnect re-try time interval uses an exponential
       back-off so that the initial delay is 5 seconds after the first unsuccessful attempt, then 10 seconds, then 20 seconds, then 40 seconds and
       then 80 seconds thereafter.

       The environment variable PMCD_RECONNECT_TIMEOUT may be used to redefine the back-off intervals, see PMAPI(3).

       If the reconnection succeeds, pmReconnectContext returns handle.

       If handle identifies a context associated with an archive source of metrics, pmReconnectContext does nothing and returns handle.

       Calling pmReconnectContext with a handle identifying a currently connected context will cause the connection to be broken before any recon-
       nection is attempted.

       Note  that  even  in  the case of a successful reconnection, pmReconnectContext does not change the current Performance Metrics Application
       Programming Interface (PMAPI) context.

       When attempting to connect to a remote pmcd(1) on a machine that is booting, pmReconnectContext could potentially block	for  a	long  time
       until  the  remote  machine  finishes its initialization.  pmReconnectContext will abort and return an error if the connection has not been
       established after some specified interval has elapsed.  The default interval is 5 seconds.  This  may  be  modified  by	setting  PMCD_CON-
       NECT_TIMEOUT in the environment to a real number of seconds for the desired timeout.  This is most useful in cases where the remote host is
       at the end of a slow network, requiring longer latencies to establish the connection correctly.

ENVIRONMENT

       PMCD_CONNECT_TIMEOUT
	      Timeout period (in seconds) for pmcd(1) connection attempts.

       PMCD_RECONNECT_TIMEOUT
	      Redefines the back-off intervals - refer to PMAPI(3).

SEE ALSO

       pmcd(1), PMAPI(3), pmNewContext(3) and pmUseContext(3).

DIAGNOSTICS

       PM_ERR_NOCONTEXT

	      handle does not identify a valid PMAPI context

       -ETIMEDOUT

	      The re-try time has not elapsed, or the reconnection is attempted and fails.

CAVEAT

       Applications that use gethostbyname(3) should exercise caution because the static fields in struct hostent may not be preserved across some
       PMAPI(3) calls.	In particular, pmNewContext(3) and pmReconnectContext(3) both may call gethostbyname(3) internally.

Performance Co-Pilot							PCP						     PMRECONNECTCONTEXT(3)