Event Routines

NAME

dciPostEvent - provider routine to post an event

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciPostEvent(
    DCIMetricId      *metricId,            /* in */
    UMAUint4         eventDataSize,        /* in */
    UMAUint4         eventDataCount,       /* in */
    UMAVarLenData    *eventData            /* in */
);

ARGUMENTS

metricId

Address of an event metric identifier for the event to be posted.

eventDataSize

Size of the event data in bytes. This must agree with the total of all size fields in the DCIEventDataAttr structures from the DCIEventAttr structure for this event registered in the DCIClassAttr structure.

eventDataCount

Number of entries in the eventData variable length array. Note that the array contains variable length entries; the size is passed by the provider to the server to enable the server to place it directly in the DCIEvent (see DCIClassAttr Diagram ) structure it creates for this event.)

eventData

The data that should be passed on in the eventData field of the DCIEvent structure for this event.

DESCRIPTION

The dciPostEvent() routine is used by a provider for event notification. The inputs to this routine are the metric identifier for the event and the associated event data. If there is no associated event data, meaning that the only information of interest for this event is simply that the event occurred, then eventDataSize must be zero. Otherwise the data given by the event pointer must conform to the event attributes structure this provider previously registered for this event. Although the DCI Server cannot verify the content of the event data it does verify that the size matches the registered attributes. Once the input arguments have been verified, then the DCI Server packages it into a DCIEvent structure along with a timestamp and forward the event to the consumer.

RETURN VALUES

The dciPostEvent() routine returns [DCI_SUCCESS] if the event was posted successfully. Otherwise, dciPostEvent() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[DCI_NOIMPLEMENTATION]

In a DCI subset implementation, the specified routine has not been implemented.

[DCI_NOTINITIALIZED]

The DCI subsystem is not currently initialised.

[DCI_SYSERROR]

An internal error has occurred (such as a shortage of resources) that may be beyond the control of the application. A vendor-specific error code is placed in the variable errno.

[DCI_INVALIDARG]

One of the input arguments is invalid: a negative value was used for numIds, bufferSize is smaller than the size of a DCIReturn structure, metricIdList was malformed, timeout was malformed or the address of dataSize was not provided and dataAddress was specified and set to a NULL.

[DCI_NOCLASS]

The requested metric class identifier is not present in the name space.

[DCI_NOINSTANCE]

The requested instance identifier is not in the name space.

DCI_NODATUMID]

The [associated metricId specified a nonexistent datumId for the specified class.

[DCI_NOMETRIC]

There is no such metric identifier in the name space.

[DCI_NOTEVENTMETRIC]

The associated metricId specified a datumId which is not an event metric.

[DCI_NOACCESS]

The caller does not have permission to find out if a requested instance identifier exists or does not have access to a metric identifier.

NAME

dciWaitEvent - wait for one or more events

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciWaitEvent(
    DCIHandle         handle,               /* in */
    DCIMetricId       *metricIdList,        /* in */
    UMAUint4          numIds,               /* in */
    DCIEventReturn    **bufferAddress,      /* in/out */
    UMAUint4          bufferSize,           /* in */
    void              **dataAddress,        /* in/out */
    UMAUint4          *dataSize,            /* in/out */
    UMATimeval        *timeout,             /* in */
    UMAUint4          eventFlags            /* in */
);

ARGUMENTS

handle

A handle opened on events to be waited for. This must contain at least one valid event.

metricIdList

Address of a list of metric identifiers, each of which must be an open event in the handle argument. These events specify a subset of the handle on which to base this function call. If metricIdList is zero, then the function call is based on all event metrics in the handle.

numIds

The number of input metric identifiers.

bufferAddress

Points to the address of a return status buffer.

bufferSize

The size of the return status buffer.

dataAddress

Points to an address of a buffer to use to store event data. If dataAddress is NULL, then the system allocates a buffer, setting the value of dataSize to the size of the allocated buffer.

dataSize

Address of the size of the return data buffer.

timeout

Pointer to a UMATimeVal structure that specifies the maximum time to wait for this request to complete. When timeout is NULL, dciWaitEvent() blocks indefinitely.

eventFlags

Bitmapped flags as described below.

DESCRIPTION

The dciWaitEvent() routine waits for any event in both the handle and the metricIdList to occur. If this metricIdList subset of the handle specifies a wildcard that when expanded would contain any polled metrics, that is, non events, they are ignored without producing any errors. An error results if any individual, that is, non-wildcarded, polled metric is specified by the handle and metricIdList combination.

dciWaitEvent() always separates the event data it is returning and the status return buffers in order to allow consumers in an event data acquisition loop to archive successfully acquired data and discard the status structure. dciWaitEvent() uses bufferAddress to write summary information about all events that have occurred and uses dataAddress to write the associated event data. If the return status buffer address is zero, then dciWaitEvent() allocates the return status on behalf of the caller and return its address in bufferAddress. If the return data buffer address is zero, then dciWaitEvent() allocates a data buffer of size *dataSize on behalf of the caller and return its address in dataAddress. The caller is responsible for subsequently freeing the allocated memory using dciFree().

The following flags may be specified in eventFlags:

DCI_EVENT_NOBLOCK

Do not block. Return immediately. This flag is mutually exclusive with the DCI_EVENT_FILLBUFFER flag.

DCI_EVENT_FILLBUFFER

This call should block until the buffer specified by dataAddress or the system allocated buffer if dataAddress was zero, is full. Any event that could not be fully written to dataAddress without overflowing the dataAddress buffer is buffered (or lost) using the policy for the respective handle and is not be reported in the return structure for this call. This flag is mutually exclusive with the DCI_EVENT_NOBLOCK flag.

This routine can be used with the class identifier wildcard value, DCI_ALL, and instance level wildcarding. Any attribute structure changes to the subsetted name space since the handle was created, or the addition of classes and instances to wildcarded collections are indicated by an appropriate status return value. The timeout parameter allows consumers to set a maximum event wait period.

If event buffering was not specified when the handle was opened, it is highly likely that events that a consumer is interested in can be lost. If an event occurs when no consumer is blocked in dciWaitEvent() and buffering of events has not been enabled, then the event may be lost. Lost events are reported in the DCIEventReturn struct of the next dciWaitEvent() call using that handle. If buffering is enabled and the buffer is not full, the event is saved in the per handle buffer until the next dciWaitEvent() call on that handle. If the buffer space is full when the event occurs, either one or more previous events are discarded, or the current event is discarded depending on the buffering policy set in dciOpen(). If a consumer is using the metricIdList to specify only a subset of the events in the handle, then the behaviour of the system event buffering mechanisms is implementation dependent.

With no flags set, the default behaviour of dciWaitEvent() is to return after collecting only the events that are currently buffered or that occur during the call, or if none, block until at least one event has occurred. This behaviour can be modified by DCI_EVENT_NOBLOCK to allow it to return without any events occurring or by DCI_EVENT_FILLBUFFER to allow it to continue to wait for further events. Generation of status information of informational severity alone does not cause dciWaitEvent() to return prematurely.

If event data is returned from a class which could contain invalid data (the associated DCIClassAttr attribute flag has DCI_POSSIBLEINVALIDDATA set), and a the entire class of data is returned, the application is required to check each metric for validity before extracting its associated data.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciWaitEvent() call. If the timeout has expired before the call completes, then one or more of the DCIRetval structures associated with the expanded metrics will show a DCI_TIMEOUT status. If the timeout parameter is NULL, then this call is not subject to a timeout. This call can be interrupted by a delivered signal; in this case, the DCIStatus returned for the call is DCI_INTERRUPTED and it is implementation defined whether any partial results are delivered.

RETURN VALUES

The dciWaitEvent() routine returns [DCI_SUCCESS] if the following DCIEventReturn structure was written into the return status buffer, bufferAddress.

 

typedef struct DCIEventReturn {
    UMAUint4        size;
    UMAUint4        numEvents;
    UMAUint4        numLostEvents;
    UMAVarLenDescr  eventStatus;
    UMAUint4        buffer_offset;
    UMAVarLenData   data;
} DCIEventReturn;

where the structure elements are as follows:

size

Total number of bytes being returned. Must be a multiple of 4.

numEvents

Number of events being reported.

numLostEvents

Number of events in this handle lost or unrecorded for any reason since the last time a DCIEventReturn structure was returned for this handle.

eventStatus

Descriptor for the variable sized data comprising the event status information. The event status information is a sequence of numEvents and consequent DCIStatus values, one for each event recorded in the dataAddress buffer, and in the same order.

buffer_offset

This contains the offset from the beginning of the buffer to the event data.

data

This is a place holder that conceptually contains all the data pointed to by the eventStatus.offset fields.

On return, dataAddress contains numEvents and consequent DCIEvent structures, one for each event that occurred.

If DCI_EVENT_NOBLOCK was set and no events were returned, the numEvents field of the DCIEventReturn is zero and the data area contains no DCIStatus. The numLostEvents field may be non zero in this case if events were lost since the last dciWaitEvent() call using this handle.

Note that [DCI_SUCCESS] could be returned and no events collected if the handle contained no events or if all events in the handle were disabled.

If [DCI_SUCCESS] was not returned, dciWaitEvent() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[DCI_NOIMPLEMENTATION]

In a DCI subset implementation, the specified routine has not been implemented.

[DCI_NOTINITIALIZED]

The DCI subsystem is not currently initialised.

[DCI_SYSERROR]

An internal error has occurred (such as a shortage of resources) that may be beyond the control of the application. A vendor-specific error code is placed in the variable errno.

[DCI_NOSPACE]

The provided buffer is too small for the return structure. The size field of the DCIReturn structure indicates the buffer size which would have held all the associated return values. If the count field of the DCIReturn structure is nonzero, then partial data was written to the buffer.

It is implementation defined whether or not partial data is available in the buffer in the case of a DCI_NOSPACE error (for example, on a dciGetData() call). It is also implementation defined whether or not the state of the DCI changes given that a DCI_NOSPACE error has occurred (for example, on a wildcarded dciRemoveInstances() call). In each of the above cases, individual DCIRetval status values must be examined to determine whether or not the data is valid, and whether or not the requested change actually occurred.

[DCI_ALLOCATIONFAILURE]

The DCI library could not allocate the memory for the return buffer.The application could attempt to allocate its own memory and try the request again.

[DCI_BADHANDLE]

The handle provided is not currently open.

[DCI_INVALIDARG]

One of the input arguments is invalid: a negative value was used for numIds, bufferSize is smaller than the size of a DCIEventReturn structure, or metricIdList was malformed.

[DCI_BADFLAGS]

One or more mutually exclusive flags were used together.

[DCI_TIMEOUT]

A timeout occurred during data collection. Some events may have been reported.

[DCI_INTERRUPTED]

This call was interrupted by a signal and did not complete. It is implementation defined whether partial results are provided. If partial results are provided, the application may need to amend the request list to avoid duplicating completed requests.

The summary status of all individual DCIRetval structure status members is stored in the DCIReturn structure status member. This summary status represents the highest severity of status returned among all DCIRetval structures.

[DCI_FAILURE]

There was at least one failure status.

[DCI_WARNING]

There was at least one warning status and no failure status.

[DCI_INFORMATIONAL]

There was at least one information status and no failure or warning status.

[DCI_SUCCESS]

All status returned was successful.

For each DCIRetval structure returned, the status member may contain the following:

[DCI_SUCCESS]

The request succeeded and there may be associated data.

[DCI_NOCLASS]

The requested metric class identifier is not present in the name space.

[DCI_NOINSTANCE]

There is no such instance identifier in the handle.

[DCI_NOMETRIC]

There is no such metric identifier in the name space.

[DCI_NOTEVENTMETRIC]

The associated metricId specified a datumId which is not an event metric.

[DCI_NOACCESS]

The caller does not have permission to find out if a requested instance identifier exists or does not have access to a metric identifier.

[DCI_NOSPACE]

There was not enough room in the return buffer to write the event data for the fired event.

It is implementation defined whether or not partial data is available in the buffer in the case of a DCI_NOSPACE error (for example, on a dciGetData() call). It is also implementation defined whether or not the state of the DCI changes given that a DCI_NOSPACE error has occurred (for example, on a wildcarded dciRemoveInstances() call). In each of the above cases, individual DCIRetval status values must be examined to determine whether or not the data is valid, and whether or not the requested change actually occurred.

[DCI_CLASSESADDED]

This new class has been added within the scope of a wildcarded class request.

[DCI_INSTANCESADDED]

This new instance has been added within the scope of a wildcarded instance request.

[DCI_NOTENABLED]

The requested metric is currently not enabled by its provider.

[DCI_TIMEOUT]

The associated metric could not be expanded or referenced during the specified timeout period. This may be because the affiliated provider could not be contacted, or because the reference was never attempted due to an existing timeout condition in the input request list.