NAME

       pmaDeltaInDom  -  generate a ``delta indom'' if two observations of an instance domain are
       different

C SYNOPSIS

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

       void pmaDeltaInDom(__pmLogInDom *old, __pmLogInDom *new, __pmLogInDom *new_delta);

       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

       Checks if two observations of the same instance domain are identical, and if they are not,
       tries to generate a ``delta indom'' to describe the differences.

       The code assumes (a) old->indom == new->indom and (b) both the instance domains are sorted
       in ascending internal instance identifier sequence; see pmaSortInDom(3) to see how to make
       the second condition true.

       The ``delta indom'' format is only supported for Version 3 archives and it is the caller's
       responsibility to determine if calling pmaDeltaInDom is appropriate, rather  than  calling
       pmaSameInDom(3) which is the preferred method for V2 archives.

       pmaDeltaInDom returns 0 if the old and new instance domains are the same.

       A  return  value  of  1  indicates that the instance domains are different and the ``delta
       indom'' format is not more efficient; in this case new_delta is not modified.

       A return value of 2 indicates that the instance domains are different  and  new_delta  has
       been set up to describe the ``delta indom'' encoding of the differences;  in this case the
       caller is responsible for freeing new_delta->instlist and new_delta->namelist.

       The instance domains are considered different if any of the following hold:

       1.  old->numinst != new->numinst

       2.  For some i, old->instlist[i] != new->instlist[i]

       3.  For some i, the strings pointed to by old->namelist[i] and  new->instlist[i]  are  not
           identical

DELTA INDOM FORMAT

       As  for  a  regular  instance  domain,  new_delta->numinst  defines the number of instance
       specifications.

       If new_delta->namelist[i] == NULL then the instance identified  by  new_delta->instlist[i]
       has been deleted from the instance domain.

       If  new_delta->namelist[i]  != NULL then the instance identified by new_delta->instlist[i]
       has been added to the instance domain.

       Because the ``delta indom'' is only likely to have short-term relevance to the caller, the
       new_delta->namelist[i]  entries that are not NULL will point back into old->namelist[j] or
       new->namelist[k] and so old and new should not be freed until the caller has finished with
       new_delta.

SEE ALSO

       PMAPI(3), pmaSortInDom(3) and pmaSameInDom(3).