PMDAEVENTARRAY(3)					     Library Functions Manual						 PMDAEVENTARRAY(3)

NAME

       pmdaEventNewArray, pmdaEventResetArray, pmdaEventReleaseArray, pmdaEventAddRecord, pmdaEventAddMissedRecord, pmdaEventAddParam, pmdaEvent-
       GetAddr - utilities for PMDAs to build packed arrays of event records

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/impl.h>
       #include <pcp/pmda.h>

       int pmdaEventNewArray(void);
       int pmdaEventResetArray(int idx);
       int pmdaEventReleaseArray(int idx);
       int pmdaEventAddRecord(int idx, struct timeval *tp, int flags);
       int pmdaEventAddMissedRecord(int idx, struct timeval *tp, int nmissed);
       int pmdaEventAddParam(int idx, pmID pmid, int type, pmAtomValue *avp);
       pmEventArray *pmdaEventGetAddr(int idx);

       cc ... -lpcp

DESCRIPTION

       A Performance Metrics Domain Agent (PMDA) that wishes to export event records (or trace records) is encouraged to  use  a  metric  of  type
       PM_TYPE_EVENT to encode a group of event records into a single packed array.

       The packed array of event records format is defined in <pcp/pmapi.h> and consists of a pmEventArray structure, containing a variable number
       of pmEventRecord structures, each of which contains a variable number of pmEventParameter structures, which in turn may contain a  variable
       length value for each parameter of each event record.

       The  routines described here are designed to assist the PMDA developer in building a packed array of event records, and managing all of the
       memory allocations required to hold each instance of an array of event records in a contiguous buffer.  Normal use would be as part of  PM-
       DA's pmdaFetchCallBack method.

       pmdaEventNewArray  is used to create a new event array.	The return value is a small integer that is used as the idx parameter to the other
       routines to identify a specific event array.  If needed, a PMDA can create and use multiple event arrays.

       To start a new cycle and refill an event array from the beginning, call pmdaEventResetArray.

       If the PMDA has finished with an event array, pmdaEventReleaseArray may be used to release the underlying storage and ``close''	the  event
       array so that subsequent attempts to use idx will return PM_ERR_NOCONTEXT.

       To  start  a  new  event record, use pmdaEventAddRecord.  The timestamp for the event record is given via tp and the flags parameter may be
       used to set the control field that determines the type of the event record - flags may be the  bit-wise	``or''	of  one  or  more  of  the
       PM_EVENT_FLAG_* values defined in <pcp/pmapi.h> (but note that PM_EVENT_FLAG_MISSED should not be used in this context).

       If  event  records  have  been missed, either because the PMDA cannot keep up or because the PMAPI client cannot keep up, then pmdaEventAd-
       dMissedRecord may be used.  idx and tp have the same meaning as for pmdaEventAddRecord and nmissed is the number of event records that have
       been missed at this point in the time-series of event records.  pmdaEventAddMissedRecord may be called multiple times for a single batch of
       event records if there are more than one ``missed event record'' episode.

       Once an event record has been started by calling pmdaEventAddRecord, one or more event parameters may  be  added  using	pmdaEventAddParam.
       The  pmid  and  type parameters decribe the PMID of the parameter and the data type (one of the PM_TYPE_* values from <pcp/pmapi.h>) of the
       value that is passed via avp.  type should one where the size of the value is implied by the type or by the length of a string  value  (for
       PM_TYPE_STRING) or encoded within avp->vbp (for PM_TYPE_AGGREGATE).

       Once the packed array has been constructed, pmdaEventGetAddr should be used to initialize the ea_type and ea_len fields at the start of the
       pmEventArray and return the base address of the event array that is assigned to	the  vp  field	of  the  pmAtomValue  structure  that  the
       pmdaFetchCallBack method should return.

EXAMPLE

       The following skeletal code shows how these routines might be used.

       int	       sts;
       int	       myarray;
       int	       first = 1;
       pmEventArray    eap;

       if (first) {
	  first = 0;
	  if ((myarray = pmdaEventNewArray()) < 0) {
	     // report error and fail
	  }
       }

       pmdaEventResetArray(myarray);

       // loop over all event records to be exported
       ... {
	  struct timeval   stamp;
	  int		   flags;

	  // establish timestamp and set flags to 0 or some combination
	  // of PM_EVENT_FLAG_POINT, PM_EVENT_FLAG_START, PM_EVENT_FLAG_ID,
	  // etc
	  if ((sts = pmdaEventAddRecord(myarray, &stamp, flags)) < 0) {
	     // report error and fail
	  }

	  // loop over all parameters for this event record
	  ... {
	     pmID	   pmid;
	     int	   type;
	     pmAtomValue   atom;

	     // construct pmid, type and atom for the parameter and
	     // its value
	     if ((sts = pmdaEventAddParam(myarray, pmid, type, &atom)) < 0) {
	     // report error and fail
	     }
	  }

	  // if some event records were missed (could be at the start
	  // of the exported set, or at the end, or in the middle, or
	  // a combination of multiple missed record episodes)
	  ... {
	     int	      nmiss;
	     struct timeval   stamp;

	     if ((sts = pmdaEventAddMissedRecord(myarray, &stamp, nmiss)) < 0) {
	     // report error and fail
	     }
	  }
       }

       // finish up
       eap = pmdaEventGetAddr(myarray);

SEE ALSO

       pmdaEventNewQueue(3), pmdaEventNewClient(3), PMDA(3) and pmEventFlagsStr(3).

Performance Co-Pilot							PCP							 PMDAEVENTARRAY(3)