Previous section.

UMA Data Capture Interface (DCI)
Copyright © 1997 The Open Group

DCI Routines Overview

Routine Summary and Subset Implementations

Two groupings of the DCI routines are next presented. The first divides the routines into four categories:

Polled metric consumer routines are those used by metrics consumers to interrogate the name space, and obtain metric values. Polled metrics provider routines are those used by the metrics providers to populate and manage the name space, and make metric values available to the DCI Server. The event handling routines are used by both event providers and consumers to manage the registration and delivery of events. The remaining routines include utilities and administrative functions used by both providers and consumers to: manage memory, manage secure access, manage metric enablement and control event buffering policy. These categories are shown in DCI Routines, Grouped by Use . Subsequent chapters in this specification cover each category separately.


Consumer Provider
dciInitialize dciRegister
dciTerminate dciUnregister
dciListClassId dciAddInstance
dciListInstanceId dciRemoveInstance
dciOpen dciWaitRequest
dciClose dciPostData
dciGetClassAttributes
dciGetInstAttributes
dciGetData  
dciAddHandleMetric  
dciRemoveHandleMetric  
Event Handling Routines
dciWaitEvent
dciPostEvent
Other Routines
dciSetClassAccess
dciSetInstAccess
dciAlloc
dciFree
dciConfigure
dciSetData
dciPerror


Table: DCI Routines, Grouped by Use

The reason for partitioning the routines into provider and consumer groups is that this enables anyone writing provider or consumer code to focus quickly on the relevant routines. It also enables the design of a consistent set of interfaces within the grouping.

The second grouping of DCI routines, by function type, is presented in DCI Routines, Grouped by Implementation Subset . This grouping provides guidelines for a staged implementation of the DCI routines.

With this grouping, the Data Capture Interface can be divided into five subsets:

Again, it is intended that, as DCI implementations become widespread and more mature, there will be no subset implementations. If one chooses to do a subset implementation, then the unimplemented library routines should be stubbed and should return the error DCI_NOIMPLEMENTATION in the event they are accessed.

Grouping of the DCI routines by implementation subset is given in the following table:


Basic Support Multiple Providers
dciOpen dciRegister
dciClose dciAddInstance
dciListClassId dciUnregister
dciListInstanceId dciWaitRequest
dciInitialize dciPostData
dciTerminate dciRemoveInstance
dciGetData  
dciGetClassAttributes  
dciGetInstAttributes  
dciAddHandleMetric  
dciRemoveHandleMetric  
dciConfigure  
dciFree
dciAlloc  
dciPerror  
Access Control Event Support
dciSetClassAccess dciWaitEvent
dciSetInstAccess dciPostEvent
Set Capability Support
dciSetData


Table: DCI Routines, Grouped by Implementation Subset

There are a number of reasons why the DCI specification currently describes subset implementations:

  1. It lowers the initial implementation cost. One can ship a DCI compliant system quickly and then choose to add functions in the future.

  2. It increases portability of the DCI to operating systems which cannot easily implement certain functions. For example, some systems have no notion of access control or could not support event delivery.

  3. It allows for implementations which have no underlying operating system support. Tool vendors may want to implement a DCI interface in advance of their system vendors to increase the portability of their tool set.

The following sections provide additional information on how the routines are partitioned and the implications of each subset for the implementor.

Basic Support

Basic support would be the most limited level. It would support the interrogation of a fixed metrics name space and the acquisition of polled data. This level of service is similar to that available on many current systems. There is no provision for the run time modification of the metrics name space or user space providers. The routines that must be present in a basic implementation are:

dciOpen
If the indicated metrics are present in the namespace, a handle is returned. This handle can then be used in subsequent DCI calls (for example, dciGetData() to refer to the same metrics. The handle provides a guarantee to consumers that any DCI operation using this same handle produce informational return status if a wildcarded class or instance has been newly registered or instantiated.

dciClose
This routine invalidates the handle provided by the dciOpen() call.

dciListClassId
Allow consumers to look up a list of metric class identifiers in the metrics name space.

dciListInstanceId
Allow consumers to look up a list of instance identifiers in the metrics name space.

dciInitialize
Allow both consumers and providers to tell the DCI implementation that they are initiating a sequence of DCI operations.

dciTerminate
Allow both consumers and providers to tell the DCI implementation that they are terminating a sequence of DCI operations.

dciGetData
Allow consumers to get polled metric data.

dciGetClassAttributes
Allow consumers to acquire the metric class attributes.

dciGetInstAttributes
Allow consumers to acquire the metric instance attributes.

dciAddHandleMetric
Allow consumers to add metrics (polled or event) to an already open handle.

dciRemoveHandleMetric
Allow consumers to remove metrics (polled or event) from an already open handle.

dciConfigure
Allow consumers to transmit configuration requests to providers.

dciFree
Allow consumers to release return buffer and data buffer memory that had been allocated by the server.

dciAlloc
Allow consumers to allocate buffer space for use by the server. Space must be freed with the dciFree call.

dciPerror
Translate a dciStatus value into a corresponding text string.

Implementation of the Basic Support subset is required. The #define symbol _DCI_SUBSET_BASIC must be defined to have value:

DCI_SUBSET_BASIC (0x01)

(see the <dci.h> header file in C Language Header Files .

Multiple Providers

The first optional subset allows for multiple providers. For this level, one must implement those routines which allow the providers to modify the name space and register their ability to provide metrics:

dciRegister
Allow providers to register a list of metrics.

dciAddInstance
Allow providers to add an instance to a class.

dciUnregister
Allow providers to unregister a list of metrics.

dciWaitRequest
Allow providers to wait for service requests.

dciPostData
Allow providers to actively transmit polled metrics.

dciRemoveInstance
Allow providers to remove a list of instances from the name space.

Implementation of Multiple Providers is optional. If implemented, the #define symbol _DCI_SUBSET_MULTIPLE_PROVIDERS must be defined to have value:

DCI_SUBSET_MULTIPLE_PROVIDERS (0x02)

If not implemented, the #define symbol _DCI_SUBSET_MULTIPLE_PROVIDERS must be defined as 0 (see <dci.h> header file in C Language Header Files ).

Access Control

Another optional API subset enables the access control mechanism. Even if the access control routines are in place the implementor can choose to specify how much access control is supported, just as implementations can choose the appropriate security levels. One can imagine implementations that want to streamline access checking in favour of performance. These implementations could check access control only at the group level and either return the [DCI_NOIMPLEMENTATION] reply for attempts to set or get access control information at the other levels or simply silently accept the request. To implement access control one must add the routines:

dciSetClassAccess
Allow the provider to set the default or explicit access control information for a set of metric classes.

dciSetInstAccess
Allow the provider to set the default or explicit access control information for a set of metric instances.

In addition, all consumer routines would be modified to perform access control checks (using the provider-set access control information).

Implementation of Access Control is optional. If implemented, the #define symbol _DCI_SUBSET_ACCESS_CONTROL must be defined to value:

DCI_SUBSET_ACCESS_CONTROL (0x04)

If not implemented, the #define symbol _DCI_SUBSET_ACCESS_CONTROL must be defined as 0 (see the <dci.h> header file in C Language Header Files ).

Event Delivery Support

Event delivery support extends the DCI to include event metrics (Basic Support provides only for polled metric support). Event delivery requires buffering, as specified in the dciOpen() call. It facilitates asynchronous delivery of information, for example, the removal or addition of certain instances, as well as tracing: high bandwidth delivery of system performance related events. Event delivery adds the following two calls to the DCI service.

dciWaitEvent
A consumer routine to retrieve one or multiple events.

dciPostEvent
A provider routine to post an event.

Implementation of Event Support is optional. If implemented, the #define symbol _DCI_SUBSET_EVENT_SUPPORT must be defined to have value:

DCI_SUBSET_EVENT_SUPPORT (0x08)

If not implemented, the #define symbol _DCI_SUBSET_EVENT_SUPPORT must be defined as 0 (see the <dci.h> header file in C Language Header Files ).

Set Capability

A separate DCI subset, enabling the implementation of other protocols, is the set capability. Although not required for pure measurement oriented systems as defined by UMA, it enables other protocols such as SNMP to make use of the DCI functions. The following call is added to the DCI service.

dciSetData
A consumer routine to alter information in one or multiple providers.

Implementation of Set Capability is optional. If implemented, the #define symbol _DCI_SUBSET_SET_CAPABILITY must be defined to have value:

DCI_SUBSET_SET_CAPABILITY (0x10)

If not implemented, the #define symbol _DCI_SUBSET_SET_CAPABILITY must be defined as 0 (see the <dci.h> header file in C Language Header Files ).

Routine Status Values

The following is a list of the return values for the Data Capture Interface routines. A return value, of the type DCIStatus, is presented in 3 separate locations for each DCI routine that is issued: in each element of the DCIRetval array (if the particular DCI routine is specified to return such an array), in the DCIReturn structure and as the direct return value of the DCI routine itself. The "status" member of each DCIRetval structure returned indicates the status of the result for the particular MetricId or ClassId referenced by the MetricOffset member. The status DCIReturn is a "summary" status which reflects the status for all DCIRetval structures returned. The return value of the DCI routine represents whether that call succeeded or the specific reason for its failure.

In the latter case, the DCIStatus value returned must be carefully examined before the DCIReturn and DCIRetval structures are referenced. The DCI routine may return "fatal" errors, indicating that the call could not be made and that the DCIReturn structure is not valid and should not be dereferenced. Such "fatal" errors may arise because:

In such a case, the caller can expect no DCIReturn data and is obliged to deallocate any memory the DCI Server had allocated for the caller. For example, many of the DCI routines accept a bufferAddress which may be set to zero if the DCI Server should allocate a properly sized memory object. If the contents of bufferAddress were set to NULL before the call and achieved a non-NULL value after the DCI routine which returned the "fatal" DCIStatus, the caller must then deallocate this memory with dciFree().

In the case of [DCI_SYSERROR], the underlying system had some failure that caused the routine to fail. Such errors might be due to lack of system resources, address faults or other conditions which might be uncontrollable by the application. In this case the DCI routine may succeed if issued a second time (if the error was a transient one), or may continue to return [DCI_SYSERROR]. The underlying error is placed in errno; it is implementation-defined how the application may attempt recovery from the error.

There is one exception to the description of "fatal" errors above. If the caller had preallocated a buffer for the return value and it proved too small for the data requested, the DCIStatus returned by the routine is [DCI_NOSPACE]. In this case, the first word of the buffer contains the buffer size that would have held this request. This size could be used to preallocate a larger buffer and retry the call.

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.

Although the DCI routine may have executed properly, the DCIStatus value stored in the status member of the DCIReturn structure represents the summary of any individual DCIRetval status. If all individual DCIRetval status values are DCI_SUCCESS, then the summary value is [DCI_SUCCESS]. However, if 1 or more of the DCIRetval structures show an error, warning or informational status member, then the summary status will not be [DCI_SUCCESS], but rather represent the most serious severity status among the DCIRetval structures. The summary status then, may contain [DCI_SUCCESS], [DCI_INFORMATIONAL], [DCI_WARNING] or [DCI_FAILURE]. To determine the severity class of any returned status value, the application need only bitwise logically "and" the status with [DCI_SUCCESS], [DCI_INFORMATIONAL], [DCI_WARNING], [DCI_FAILURE] or [DCI_FATAL].

Each DCIRetval structure presents its own status. That status may be classified as success, failure, warning or informational. A failure means that the operation requested of the associated MetricId or ClassId could not be completed. A warning indicates that the operation was well-formed, but could not be completed for some reason. An informational status is one for which the data requested is returned successfully, but with some possible change in state since the last request, or possibly with additional information useful to the application.

Every call that has been passed a valid handle can return an informational status of [DCI_CLASSADDED] or [DCI_INSTANCEADDED]. The [DCI_CLASSADDED] status is generated each time that a wildcarded class id expands into a new class. A new class is one that has been registered after the metric id had been added to the handle, by dciOpen() or dciAddHandleMetric(), and has not since returned a [DCI_CLASSADDED] status for this handle. The [DCI_CLASSADDED] status message is returned, in the DCIRetval structure, with and only with the first piece of returned information associated with the new class. Similarly, [DCI_INSTANCEADDED] status is generated each time a wildcarded instance id expands into a new instance. A new instance is one that was added to a class after the metric id had been added to the handle, using dciOpen() or dciAddHandleMetric().

The following fatal errors are returned from the DCI routine itself.

[DCI_ALLOCATIONFAILURE]

[DCI_BADFLAGS]

[DCI_BADHANDLE]

[DCI_INITIALIZED]

[DCI_INTERRUPTED]

[DCI_INVALIDARG]

[DCI_NOIMPLEMENTATION]

[DCI_NOSPACE]

[DCI_NOTINITIALIZED]

[DCI_NOTPRESENT]

[DCI_SYSERROR]

The following status success value is returned from the DCI routine itself:

[DCI_SUCCESS]

The following summary status values are stored in the DCIReturn structure:

[DCI_FAILURE]

[DCI_WARNING]

[DCI_INFORMATIONAL]

[DCI_SUCCESS]

The following errors are returned as individual status:

[DCI_BADCONFIRM]

[DCI_CLASSEXISTS]

[DCI_CLASSNOTEMPTY]

[DCI_CLASSNOTPERSISTENT]

[DCI_DCIMAJORUNSUPPORTED]

[DCI_DCIMINORUNSUPPORTED]

[DCI_DERIVEDDATA]

[DCI_EVENTSUPPORT]

[DCI_INSTANCEEXISTS]

[DCI_INSTANCENOTPERSISTENT]

[DCI_INVALIDDATA]

[DCI_INVALIDFIELD]

[DCI_INVALIDMETHODOP]

[DCI_METHODERROR]

[DCI_METHODOPNOTSUPPORTED]

[DCI_METHODTYPEUNAVAILABLE]

[DCI_NOACCESS]

[DCI_NOCLASS]

[DCI_NODATUMID]

[DCI_NOINSTANCE]

[DCI_NOMETRIC]

[DCI_NOTENABLED]

[DCI_NOTEVENTMETRIC]

[DCI_NOTEXT]

[DCI_NOTPOLLEDMETRIC]

[DCI_NOTQUERYABLE]

[DCI_NOTRESERVABLE]

[DCI_NOTRESERVED]

[DCI_NOTSETTABLE]

[DCI_NOWILDCARD]

[DCI_RESERVED]

[DCI_SUBSETUNSUPPORTED]

[DCI_TIMEOUT]

The following warnings are returned as individual status:

<none defined at this time>

The following informational values are returned as individual status:

[DCI_CLASSADDED]

[DCI_INSTANCEADDED]

[DCI_INVALIDDATAPRESENT]

[DCI_NOSUCHTRANSACTION]

The following success values are returned as individual status:

[DCI_SUCCESS]

The DCIStatus values are defined as follows:

[DCI_ALLOCATIONFAILURE]

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

[DCI_BADCONFIRM]

The reservation confirmation is either invalid or has expired.

[DCI_BADFLAGS]

The flags argument was malformed, perhaps with conflicting flags specified.

[DCI_BADHANDLE]

The handle provided is not currently valid. The handle must be that returned from a dciOpen() call.

[DCI_CLASSADDED]

The specified class has been added to the wildcarded set of classes previously opened since the last time this set of classes was expanded. This status is transient and is not returned the next time the expanded set is expanded into this class.

[DCI_CLASSEXISTS]

This class could not be registered because it already exists.

[DCI_CLASSNOTEMPTY]

Class could not be removed because either there are subclasses still registered, or instances still defined.

[DCI_CLASSNOTPERSISTENT]

The parent class is not persistent and the associated DCIClassAttr specifies persistence.

[DCI_DCIMAJORUNSUPPORTED]

The specified DCI Version major number is not supported by the DCI Server.

[DCI_DCIMINORUNSUPPORTED]

The specified DCI Version major number is supported by the DCI Server, but the specified minor version number is not.

[DCI_DERIVEDDATA]

An attempt was made to retrieve (or set) a metric that has type DCI_DERIVED. Derived data cannot be retrieved; instead, the metric's DCIDatumId should be examined to determine which related metrics should be obtained, and what kind of computation should be performed to actually obtain the desired value.

[DCI_EVENTSUPPORT]

The consumer has attempted to open an event metric with format and content requirements beyond those supported by the registering provider. The provider will form the conjunction ("and") of the provided bit map with the registered bit map to determine the format and content of event data for this event metric.

[DCI_FAILURE]

Summary status for the case where at least 1 returned individual status was an error.

[DCI_FATAL]

The called DCI routine could not complete due to input argument or system errors and any associated DCIReturn may be incomplete and should not be referenced.

[DCI_INFORMATIONAL]

Summary status for the case where at least 1 returned individual status was informational and there were no individual error or warning status values returned.

[DCI_INITIALIZED]

The DCI subsystem is already initialised.

[DCI_INSTANCEEXISTS]

This instance could not be added because it already exists.

[DCI_INSTANCEADDED]

The specified instance has been added to the wildcarded set of instances previously opened since the last time this set of instances was expanded. This status is transient and is not returned the next time the expanded set is expanded into this instance.

[DCI_INSTANCENOTPERSISTENT]

The parent class is not persistent and the associated DCIInstAttr specifies persistence.

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

[DCI_INVALIDARG]

One or more of the input arguments to the DCI routine were malformed.

[DCI_INVALIDDATA]

An attempt was made to retrieve (or set) a metric that is invalid for this particular class instance.

[DCI_INVALIDDATAPRESENT]

The associated class of data referenced contains at least one invalid metric. Each metric must be examined before use.

[DCI_INVALIDFIELD]

One or more of the associated argument structures contained an invalid field specification.

[DCI_INVALIDMETHODOP]

The method operation specified is not a valid operation.

[DCI_METHODERROR]

An error has occurred in the method invoked to retrieve or set the requested metric.

[DCI_METHODOPNOTSUPPORTED]

The method operation may not be specified in conjunction with this method type.

[DCI_METHODTYPEUNAVAILABLE]

The specified method "type" member is one of those documented in this specification, but which is not available on this platform. Only DCI_WAIT is guaranteed to be available on all implementations.

[DCI_NOACCESS]

The calling process does not have permission to retrieve information about the requested metric or to initialise a connection to the DCI server.

[DCI_NOCLASS]

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

[DCI_NODATUMID]

The specified datumId does not exist.

[DCI_NOIMPLEMENTATION]

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

[DCI_NOINSTANCE]

There is no such instance identifier in the name space.

[DCI_NOMETRIC]

There is no such metric identifier in the name space.

[DCI_NOSPACE]

The provided buffer is too small for the return structure.

[DCI_NOSUCHTRANSACTION]

The specified transactionId is either invalid or the associated transaction was cancelled.

[DCI_NOTENABLED]

The requested metric is currently not enabled by its provider.

[DCI_NOTEXT]

No label has been specified with metric.

[DCI_NOTEVENTMETRIC]

An event metric was required and the requested metric identifier was not for such a metric type.

[DCI_NOTINITIALIZED]

The DCI subsystem is not currently initialised.

[DCI_NOTPOLLEDMETRIC]

A polled metric was required and the requested metric identifier was not for such a metric type.

[DCI_NOTPRESENT]

The DCI service is not available.

[DCI_NOTQUERYABLE]

The associated metric does not support being queried.

[DCI_NOTRESERVABLE]

The associated metric does not support being reserved.

[DCI_NOTRESERVED]

The associated metric could not be released because it was not already reserved.

[DCI_NOTSETTABLE]

The associated metric does not support being set.

[DCI_NOWILDCARD]

A wildcard cannot be used in this context.

[DCI_RESERVED]

The associated metric is already reserved by another consumer.

[DCI_SUBSETUNSUPPORTED]

One or more of the specified DCI API subsets are not supported by the DCI Server.

[DCI_SUCCESS]

The specified request was free of errors, warnings or informational return status.

[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_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.

[DCI_WARNING]

Summary status for the case where at least 1 returned individual status was a warning and there were no individual error status values returned.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index