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 reconnection 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_CONNECT_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.