NAME

       pmaTryDeltaInDom  -  try  to  translate a physical indom record from a ``full indom'' to a
       ``delta indom''

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/libpcp.h>
       #include <pcp/archive.h>

       int pmaTryDeltaInDom(__pmLogCtl *lcp, __int32_t **rbuf, __pmLogInDom *lidp);

       cc ... -lpcp_archive -lpcp

CAVEAT

       This documentation is intended for internal Performance Co-Pilot (PCP) developer use.

       These interfaces are not part of the PCP APIs that are guaranteed to remain  fixed  across
       releases,  and  they may not work, or may provide different semantics at some point in the
       future.

DESCRIPTION

       The input instance domain is passed in as either a physical metadata record via rbuf or in
       the  ``loaded''  format  identified by lidp.  As these are alternate formats for the input
       instance domain, pmaTryDeltaInDom demands that exactly one of rbuf and lidp must be  NULL,
       else the return value is -2.

       The  input  instance  domain  is on the path to being written to the archive identified by
       lcp.

       If possible, the instance domain will be converted to the ``delta indom'' format, and  the
       converted  instance  domain  returned  via  rbuf  or  lidp  (whichever  is  not NULL).  If
       conversion takes place, any storage assocated with the input  instance  domain  will  have
       been free'd.

       The ``delta indom'' format is only supported for Version 3 archives and it is the caller's
       responsibility to determine if calling pmaTryDeltaInDom is appropriate.

       To  determine  if  the  ``delta  indom''  format   is   the   most   efficient   encoding,
       pmaTryDeltaInDom  maintains a per-instance domain cache of the last seen ``full'' instance
       domain.  To avoid data corruption, this means  pmaTryDeltaInDom  first  copies  the  input
       instance  domain.  The copy and the cache are all managed privately by pmaTryDeltaInDom so
       the caller is unaware of this activity.

       The cacheing scheme requires that the caller must call pmaTryDeltaInDom for every instance
       domain  record,  independent  of  whether  the  ``delta  indom''  format  is  likely to be
       appropriate.

DIAGNOSTICS AND RETURN VALUES

       In several places, fatal errors will trigger an error message and force the application to
       exit.

       A  return value of -1 indicates that rbuf was not NULL and the physical record therein was
       not a TYPE_INDOM (Version 3 ``full'' instance domain) record as expected.  A return  value
       of  1  means  rbuf  or  lidp  has  been  rewritten,  and is now a TYPE_INDOM_DELTA record.
       Otherwise the return value is 0.

SEE ALSO

       pmaDeltaInDom(3), PMAPI(3) and pmaUndeltaInDom(3).