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  connec­
       tion  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  accessi­
       ble.

       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  poten­
       tially block for a long time until the remote machine fin­
       ishes its initialization.  pmReconnectContext  will  abort

       lished 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  reconnec­
              tion 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(4) calls.  In particu­
       lar, pmNewContext(3) and  pmReconnectContext(3)  both  may
       call gethostbyname(3) internally.


Man(1) output converted with man2html