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.