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).

Performance Co-Pilot                                   PCP                                      PMADELTAINDOM(3)