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.

Performance Co-Pilot                                   PCP                                 PMRECONNECTCONTEXT(3)