DCI Routines Overview

Routine Summary and Subset Implementations

• polled metrics consumer routines

• polled metrics provider routines

• event handling routines.

• other routines.

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.

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:

• basic support

• multiple provider support

• access control support

• event support

• set capability support.

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:

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

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

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

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

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

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

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:

• the call failed because it was not implemented by the host

• the DCI is not currently activated

• the call failed due to some internal system error

• the call failed because the input arguments were malformed

• the call was interrupt or prematurely timed out with no data returned.

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.