Metrics Consumer Routines

NAME

dciAddHandleMetric - adds metrics to an open handle

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciAddHandleMetric(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

A handle returned from dciOpen() that has not been subsequently closed.

metricIdList

Address of a list of metric identifiers.

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.

timeout

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

DESCRIPTION

The dciAddHandleMetric() adds additional metrics to an open handle. Added metrics will be subject to the same buffering policies that are currently in use in the open handle.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciAddHandleMetric() 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.

If the return buffer address, bufferAddress, is zero when dciAddHandleMetric() is called, then dciAddHandleMetric() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciAddHandleMetric() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciAddHandleMetric() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or metricIdList was malformed.

[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_NODATUMID]

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

[DCI_NOINSTANCE]

One or more requested instance identifiers are not present in the name space.

[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_NOTQUERYABLE]

The specified metric identifier could not be accessed.

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

NAME

dciAlloc - allocate memory which can be destroyed with dciFree

SYNOPSIS

#include <sys/dci.h>

void *dciAlloc(
    UMAUint4 size                           /* in */
);

ARGUMENTS

size

size in bytes of memory to be allocated.

DESCRIPTION

dciAlloc() will create a memory object of at least the size specified. The memory returned by this call must be deallocated using dciFree(), and is indistinguishable from memory allocated by the DCI server on behalf of the caller.

If dciAlloc() is issued with a size of 0 bytes, of if the data could not be returned, a (void *)0 is returned.

RETURN VALUES

dciAlloc() will either return the address of a memory object of the proper size, or a (void *)0 to indicate failure. No other error returns are specified.

NAME

dciClose - close a metrics list

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciClose(
    DCIHandle       handle                  /* in */
);

ARGUMENTS

handle

Handle that was returned from a prior dciOpen() call.

DESCRIPTION

The dciClose() routine is the counterpart of dciOpen(). It closes the handle that is associated with a list of metrics. Subsequent attempts to use the closed handle in any DCI call will fail.

dciClose() will flush any events pending on the handle. If the consumer wishes to capture these events, then a dciWaitEvent() should be issued prior to the call to dciClose().

RETURN VALUES

The dciClose() routine returns [DCI_SUCCESS] if the handle was open. Otherwise, this routine returns one of the following error values:

[DCI_NOTPRESENT]

The DCI service is not available.

[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_BADHANDLE]

The handle provided is not currently open.

NAME

dciConfigure - send configuration information to provider

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciConfigure(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    DCIConfig       *configList,            /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

Handle that was returned from a prior dciOpen() of metricIdList or a superset of metricIdlist.

metricIdList

Address of a list of DCIMetricId structures.

configList

List of DCIConfig structures, one per input DCIMetricId.

numIds

The number of DCIMetricId structures in metricIdList. It is also the number of DCIConfig structures in configList.

bufferAddress

Points to the address of a return value buffer.

bufferSize

The size of the return buffer.

timeout

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

DESCRIPTION

The dciConfigure() routine provides a communication channel between the consumer and its metrics providers. A metrics consumer can send a DCIConfig structure to the providers that deliver the metrics in metricIdList. Each DCIConfig structure in the configList corresponds to a DCIMetricId structure in the metricIdList. A handle for the metricIdList must be provided.

The metricIdList supports two special identifiers in the dciConfigure() call. A zero length instance identifier means "all current and future instances" of the given class(es). A datum identifier with the value DCI_ALL means "all current data" of the given class(es). By combining these two special identifiers, the requested operation is effectively performed on the given class(es).

The DCIConfig structure allows consumers to ask providers to enable or disable metrics, to set buffer policies in the DCI Server, and to transmit provider specific information in an opaque wrapper provided by the DCIConfig structure. This wrapper is given by the following structure:

typedef struct DCIConfig {
    UMAUint4         size;       /* total structure size, in bytes   */
    UMAUint4         flags;      /* configuration request            */
    UMAElementDescr  configData; /* descriptor for the               */
                                 /* auxiliary config info            */
    UMAVarLenData    data;       /* auxiliary config data start here */
} DCIConfig;

The bits in the lower half of the flags field are reserved for the DCI interface and those in the upper half can be locally defined. The following flags are defined:

 

DCI_ENABLE
DCI_DISABLE
DCI_BUFFER_EVENTS_DISCARD
DCI_BUFFER_EVENTS_OVERWRITE
DCI_BUFFER_EVENTS_SETSIZE
DCI_BUFFER_EVENTS_GETSIZE
DCI_BUFFER_EVENTS_GETPOLICY
DCI_CONFIGURATION

DCI_ENABLE and DCI_DISABLE are administrative commands that instruct the DCI Server to force an entire class (and its corresponding metrics) to be turned on or off. No reference counts are implied; a DCI_ENABLE, or DCI_DISABLE request is performed without regard to any other ongoing consumer activity relating to the specified metrics. If a class is disabled, the DCI Server refuses requests for any metric in that class. This operation is typically restricted to administrators (however that may be enforced). These two flags are mutually exclusive.

DCI_BUFFER_EVENTS_DISCARD and DCI_BUFFER_EVENTS_OVERWRITE instruct the DCI Server of the type of buffering policy to use for its internal event buffer. DCI_BUFFER_EVENTS_DISCARD instructs the DCI Server to drop new events when the internal event buffer is full. DCI_BUFFER_EVENTS_OVERWRITE instructs the DCI Server to overwrite the oldest event(s) in the buffer when a new event arrives and the buffer is full. The internal buffer is only of importance when a consumer does not have any outstanding dciWaitEvent() requests for a particular handle. The corresponding metric identifier is ignored for this request. These two flags are mutually exclusive.

DCI_BUFFER_EVENTS_SETSIZE and DCI_BUFFER_EVENTS_GETSIZE set and retrieve the size of the DCI Server internal event buffer, respectively. The size is encoded as a UMAUint4 in the data field of the DCIConfig structure, with the UMAElementDescr filled out accordingly. The corresponding metric identifier is ignored for this request. These two flags are mutually exclusive.

DCI_BUFFER_EVENTS_GETPOLICY retrieves the current buffering policy from the DCI Server for this handle. The corresponding metric identifier is ignored for this request. The actual policy is returned as the corresponding bitflag in the flags field of the DCIConfig structure.

DCI_CONFIGURATION requests the current configuration of the class or class instances indicated in the metricIdList. Datum identifiers are ignored by this request. The actual configuration information is returned in the DCIConfig structure. Currently, the following flags are supported:

DCI_ENABLE

DCI Server allows requests

DCI_DISABLE

DCI Server disallows requests

Any other configuration information can be encoded in the upper two words of the flags field and the opaque data section of the DCIConfig structure. This information is provider specific and is not part of the DCI specification.

For all the above requests the dciConfigure() routine returns a per-metric status, if appropriate, in the return buffer using the standard DCIReturn structure.

If the return buffer address, bufferAddress, is zero when dciConfigure() is called, then dciConfigure() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciConfigure() 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 dciConfigure() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciConfigure() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, the metricIdList was malformed, metricIdList and classIdList are NULL, metricIdList and classIdlist are both non-NULL.

[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_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_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_CLASSES_CHANGED]

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

[DCI_INSTANCES_CHANGED]

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

[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_INTERRUPTED]

The dciConfigure() call was interrupted by a signal and did not complete.

[DCI_NOTENABLED]

The associated metric is currently not enabled by its provider.

NAME

dciFree - release memory allocated by the DCI

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciFree(
    void            *ptr                    /* in */
);

ARGUMENTS

ptr

The address of memory allocated by the DCI on behalf of the caller.

DESCRIPTION

Several DCI routines have a calling sequence which allows the DCI application to provide a memory buffer or ask that the DCI itself allocated a suitably sized memory buffer. In either case, it is the obligation of the program to eventually return the memory to the appropriate allocation pool. If the DCI has successfully allocated the memory for the caller, then the caller must call dciFree() in order for that memory to be released. Note that even if a DCI call has failed, any memory allocated by the DCI must be freed by the caller using dciFree().

If the argument to dciFree() is NULL, then dciFree() immediately returns.

dciFree() should not be called following a dciTerminate() call.

RETURN VALUES

dciFree() may not check its input arguments for consistency and may return no error based on its argument.

The following errors may be returned:

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

NAME

dciGetClassAttributes - acquire metric class attributes

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciGetClassAttributes(
    DCIHandle       handle,                 /* in */
    DCIClassId      *classIdList,           /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize              /* in */
);

ARGUMENTS

handle

Handle that was returned from a prior dciOpen() of classIdList or a superset of classIdlist.

classIdList

Address of a list of DCIClassId structures.

numIds

The number of DCIClassId structures in classIdList.

bufferAddress

Points to the address of a return value buffer.

bufferSize

The size of the return buffer.

DESCRIPTION

The dciGetClassAttributes() routine is used to retrieve the attribute structures for a list of metric classes. The metric class identifiers can be optionally wildcarded. An optional handle may be provided for the classIdList: if the handle is valid and if classIdList contains wildcarded classes, then all metric classes of classIdList are confirmed to be a subset of the opened metric classes represented by handle and any newly registered classes is marked with a special informational status, DCI_CLASSES_CHANGED, in the associated DCIRetval structure. The classIdList is a subset of the opened metrics associated with handle. If the handle provided is 0 then no such confirmation or informational status is provided.

The dciGetClassAttributes() routine expands any metric class wildcards appearing in classIdList and determines if each expanded metric class is currently registered in the metrics name space. For each expanded metric class, a DCIRetval reply is created in the DCIReturn structure. The metricOffset member of each DCIRetval references the expanded DCIClassId structure and, if available, the dataOffset member references a DCIClassAttribute for the associated, registered metric class.

If the return buffer address, bufferAddress, is zero when dciGetClassAttributes() is called, then dciGetClassAttributes() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciGetClassAttributes() routine returns [DCI_SUCCESS] if the DCIReturn structure could be written. Otherwise, dciGetClassAttributes() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or classIdList was malformed.

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_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_NOCLASS]

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

[DCI_CLASSES_CHANGED]

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

NAME

dciGetData - get polled metric data

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciGetData(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    void            **dataAddress,          /* in/out */
    UMAUint4        *dataSize,              /* in/out */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

Handle that was returned from a prior dciOpen() of metricIdList or a superset of metricIdlist.

metricIdList

Address of a list of DCIMetricId structures.

numIds

The number of DCIMetricId structures in metricIdList.

bufferAddress

Points to the address of a return status buffer.

bufferSize

The size of the return status buffer.

dataAddress

Points to the address of an optional return data buffer.

dataSize

Address of the size of the optional 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, dciGetData() blocks indefinitely.

DESCRIPTION

The dciGetData() routine is used to acquire polled metrics data. dciGetData() expands any metric class and metric instance wildcards appearing in metricIdList and determines if each expanded metric class is currently registered in the metrics name space (and represents a subset of the metrics represented by the handle) and if each expanded instance is also registered. For each expanded metric identifier, a DCIRetval reply is created in the DCIReturn structure stored in the return buffer pointed to by *bufferAddress. The metricOffset member of each DCIRetval specifies a location relative to *bufferAddress and references the expanded DCIMetricId structure. The dataOffset member of each DCIRetval specifies a location relative the dataAddress argument (if the contents of dataAddress is 0, then the library allocates a buffer on behalf of the application) if split data and return information is specified. If split data and return information is not specified, then dataOffset is considered relative to bufferAddress. In either case, dataOffset refers to the requested data returned.

Note that the dciGetData() routine can optionally separate the data and status return buffers. This allows applications in a polled data acquisition loop to archive successfully acquired data and discard the status structure. To indicate that this separation is desired, the application must provide a non-NULL dataAddress argument. If applications separate the buffers, then the size of the data buffer is returned at the dataSize address and the size field of the DCIReturn structure is the size of the structure written to bufferAddress.

If the return buffer address, bufferAddress, is zero when dciGetData() is called, then dciGetData() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

dciGetData() accepts both class and instance level wildcards. If wildcards are provided, then informational status indicates whether a new class or instance has been added since the last such DCI routine was issued. The datumId may specify a single data item to be retrieved or, if the value of datumId is DCI_ALL then an entire class worth of data is returned. The application references the appropriate DCIClassAttr structures to determine that size and type of each piece of data, and in the case of the wildcarded datumId, the offset of each piece of data within the whole class of data returned. When the whole class of data is returned, variable length data values (such as those with UMADataType of UMA_TEXTSTRING) are handled specially; in this case, the data retrieved from the specified offset is itself an offset to the actual data. This is necessary to ensure that all data can be obtained from fixed offsets when the whole class is returned. The indirection for variable length data is not needed when datumId in not wildcarded.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciGetData() 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 dciGetData() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer and the data was written to the data buffer. Otherwise, dciGetData() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 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_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_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_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_CLASSES_CHANGED]

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

[DCI_INSTANCES_CHANGED]

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

[DCI_NOT_POLLEDMETRIC]

The associated metricId specified a datumId which does not correspond with a polled metric.

[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_NOTENABLED]

The associated metric is currently not enabled by its provider.

[DCI_INVALIDDATA]

The specified metric for the associated instance could not be returned because it is not valid.

[DCI_INVALIDDATAPRESENT]

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

[DCI_DERIVEDDATA]

An attempt was made to retrieve the value for a metric whose type is DCI_DERIVED.

[DCI_NOTQUERYABLE]

The specified metric identifier could not be accessed.

[DCI_METHODERROR]

The DCI Server has encountered an error in the method invoked to satisfy the request for the selected metric.

NAME

dciGetInstAttributes - acquire metric instance attributes

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciGetInstAttributes(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

Handle that was returned from a prior dciOpen() of metricIdList or a superset of metricIdlist.

metricIdList

Address of a list of DCIMetricId structures.

numIds

The number of DCIMetricId structures in metricIdList.

bufferAddress

Points to the address of a return value buffer.

bufferSize

The size of the return buffer.

timeout

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

DESCRIPTION

The dciGetInstAttributes() routine is used to retrieve the attribute structures for a list of instances. The metric identifiers can be optionally wildcarded for both class or instance. The datumId field of the DCIMetricId is ignored. An optional handle may be provided for the metricIdList: if the handle is valid and if metricIdList contains wildcarded classes, then all metric classes of metricIdList are confirmed to be a subset of the opened metric classes represented by handle and any newly registered classes is marked with a special informational status, DCI_CLASSES_CHANGED, in the associated DCIRetval structure. Similarly, if there are instance wildcards and a valid handle, then each expanded instance is confirmed to be within a subset of metric identifiers represented by the handle and any newly added instances is marked with a special informational status, DCI_INSTANCES_CHANGES. If the handle provided is 0 then no such confirmation or informational status is provided.

dciGetInstAttributes() expands any metric class and metric instance wildcards appearing in metricIdList and determines if each expanded metric class is currently registered in the metrics name space and if each expanded instance is also registered. For each expanded metric identifier a DCIRetval reply is created in the DCIReturn structure stored in the return buffer. The metricOffset member of each DCIRetval references the fully expanded DCIMetricId structure. The dataOffset member of each DCIRetval is set to an array of DCIInstAttr structures. The number of elements in this returned DCIInstAttr array is stored in the count member of the DCIRetval structure.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciGetInstAttributes() 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.

If the return buffer address, bufferAddress, is zero when dciGetInstAttributes() is called, then dciGetInstAttributes() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciGetInstAttributes() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciGetInstAttributes() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or metricIdList was malformed.

[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_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_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_CLASSES_CHANGED]

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

[DCI_INSTANCES_CHANGED]

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

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

NAME

dciInitialize - establish a connection to the Data Capture Interface

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciInitialize(
    DCIVersion    *request,     /* in */
    DCIVersion    *response     /* out */
);

ARGUMENTS

request

The structure holding the requested version.

response

The structure holding the actual version structure returned by the DCI Server.

DESCRIPTION

dciInitialize() is required for all DCI applications; it establishes a connection with the DCI Server, performing any implementation specific initialization needed. No other DCI API call may be successfully issued unless dciInitialize() returns DCI_SUCCESS. Use dciTerminate() to later disconnect from the DCI Server.

The application can request that the DCI Server provide a connection to the appropriate DCI API Version number, thus ensuring that all data structures and API semantics for the expected DCI Version are observed. Unless a fatal error occurs, the current version of the DCI Server and other information is returned in the response structure. The request argument is optional and may be replaced with a NULL pointer; in this case, the DCI library will provide a description of the current API version. The response argument is optional and may be replaced with a NULL pointer.

The DCIVersion structure is defined as follows:

 

/* 
 * DCI version structure.
 * This is passed into the dciInitialize() call as a request 
 * structure. As such, it specifies a request to connect to 
 * a specific DCI API version. A DCI version structure is 
 * also passed as an output parameter indicating the level 
 * of support that this particular DCI implementation
 * is actually making available.
 */
typedef struct DCIVersion {
    UMAUint4     DCIMajorVersion;
    UMAUint4     DCIMinorVersion;
    UMAUint4     DCISubsetMask;
    UMAUint4     DCIVendorExtensions;
} DCIVersion;

The DCIMajorVersion and DCIMinorVersion fields indicate the specification level of the DCI to which this implementation corresponds. The DCISubsetMask field is a bitmask indicating which DCI subsets are implemented; it is formed by "OR"ing the appropriate DCI_SUBSET_* constants together (see below). The DCIVendorExtensions field is implementation defined, and may be used to indicate refinements on the implementation level (for example, if a vendor produces multiple implementations of the DCI, this field can be used to distinguish those implementations).

The DCISubsets structure is a bitmask describing which of the DCI API subsets are present in a particular implementation. DCI Routines Overview describes the possible subsets. The corresponding values for the bitmask are defined as follows:

 

DCI_SUBSET_BASIC                = 0x01 
DCI_SUBSET_MULTIPLE_PROVIDERS   = 0x02 
DCI_SUBSET_ACCESS_CONTROL       = 0x04 
DCI_SUBSET_EVENT_SUPPORT        = 0x08 
DCI_SUBSET_SET_CAPABILITY       = 0x10

For example, if a consumer MAP is created using DCI API Version 1.0, it can call dciInitialize() as follows:

 

DCIVersion_1 wantedDCIversion, receivedDCIversion;
DCIStatus status;

bzero(&wantedDCIversion, sizeof(wantedDCIversion));
wantedDCIversion.DCIMajorVersion = DCI_MAJORVERSION;
wantedDCIversion.DCIMinorVersion = DCI_MINORVERSION;
wantedDCIversion.DCISubsetMask = DCI_SUBSET_BASIC;

status = dciInitialize(&wantedDCIversion, &receivedDCIversion);

if (status & DCI_FATAL) {     
                             /* could not make the call */
}
if (status & DCI_FAILURE) {
                     /* these could be due to version # */
}
if (status == DCI_SUBSETUNSUPPORTED) { 
        /* the specified subset was not fully supported */
}
if (status & DCI_SUCCESS) {
    /* 
     * check which subsets are enabled or examine the
     * vendor specific flags. Cast the response structure
     * to the appropriate data structure based on the
     * major number returned.
     */
}

RETURN VALUES

The dciInitialize() routine returns [DCI_SUCCESS] if it was able to establish a connection to the metric provider or consumer. Otherwise, this routine returns one of the following error values:

[DCI_INITIALIZED]

The DCI subsystem is already 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_NOACCESS]

The calling process does not have permission to initialise a connection to the DCI Server.

[DCI_MAJORUNSUPPORTED]

The specified DCI Version major number cannot be provided by the DCI Server. The DCIMajorVersion field of response represents the supported DCI version.

[DCI_MINORUNSUPPORTED]

The specified DCI Version major number can be provided, but the specified minor number could not. The DCIMinorVersion field of response represents the supported DCI version.

[DCI_SUBSETUNSUPPORTED]

One or more of the specified DCI subsets are not available. The DCISubsetMask in the response represents the fully supported DCI subsets. A subset can be partially supported, but dciInitialize() only reports complete support.

[DCI_NOTPRESENT]

The DCI service is not available.

NAME

dciListClassId - look up a list of metric class identifiers in the metrics name space

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciListClassId(
    DCIHandle       handle,                 /* in */
    DCIClassId      *classIdList,           /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize              /* in */
);

ARGUMENTS

handle

The handle returned from dciOpen(). It is optional and if 0, this argument is ignored.

classIdList

Address of a list of DCIClassId structures.

numIds

The number of DCIClassId structures in classIdList.

bufferAddress

Points to the address of a return value buffer.

bufferSize

The size of the return buffer.

DESCRIPTION

The dciListClassId() routine provides a list of registered classes contained in classIdList. The metric class identifiers can be optionally wildcarded. dciListClassId() expands any metric class wildcards appearing in classIdList and determines if each expanded metric class is currently registered in the metrics name space. For each expanded metric class, a DCIRetval reply is created in the DCIReturn structure. The metricOffset member of each DCIRetval references the expanded DCIClassId structure. The dataOffset member of each DCIRetval is set to 0.

If the return buffer address, bufferAddress, is zero when dciListClassId() is called, then dciListClassId() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciListClassId() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciListClassId() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or classIdList was malformed.

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_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_NOCLASS]

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

[DCI_CLASSES_CHANGED]

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

[DCI_INSTANCES_CHANGED]

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

NAME

dciListInstanceId - look up a list of instance identifiers in the metrics name space

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciListInstanceId(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

The handle returned from dciOpen(). It is optional and if 0 this argument is ignored.

metricIdList

Address of a list of DCIMetricId structures.

numIds

The number of DCIMetricId structures in metricIdList.

bufferAddress

Points to the address of a return value buffer.

bufferSize

The size of the return buffer.

timeout

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

DESCRIPTION

The dciListInstanceId() routine provides a list of valid instances contained in metricIdList. The metric class identifiers can be optionally wildcarded for both class or instance. The datumId field of the DCIMetricId is ignored. dciListInstanceId() expands any metric class and metric instance wildcards appearing in metricIdList and determines if each expanded metric class is currently registered in the metrics name space and if each expanded instance is also registered. For each expanded metric identifier, a DCIRetval reply is created in the DCIReturn structure stored in the return buffer. The metricOffset member of each DCIRetval references the fully expanded DCIMetricId structure. The dataOffset member of each DCIRetval is set to an array of DCIMetricId structures for each explicit instance. The number of elements in this returned DCIMetricId array is stored in the count member of the DCIRetval structure.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciListInstanceId() 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.

If the return buffer address, bufferAddress, is zero when dciListInstanceId() is called, then dciListInstanceId() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciListInstanceId() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciListInstanceId() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or metricIdList was malformed.

[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_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_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_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_CLASSES_CHANGED]

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

[DCI_INSTANCES_CHANGED]

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

NAME

dciOpen - open a list of metrics and obtain a handle

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciOpen(
    DCIHandle       *handle,                /* out */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMAUint4        handleFlags,            /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

A pointer to a location to return the handle.

metricIdList

Address of a list of metric class identifiers.

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.

handleFlags

Bitmapped flags as described below.

timeout

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

DESCRIPTION

The dciOpen() routine instructs the Data Capture service to perform an access check for every metric in metricIdList. If successful, a handle is returned which can be used in subsequent operations to access all or some of the metrics in metricIdList.

Metrics can be dynamically added to or deleted from a handle using dciAddHandleMetric() and dciRemoveHandleMetric().

The dciOpen() routine also allows the specification of a handle specific buffering scheme for provider generated events. Event buffering may be desired when a consumer wants to minimise loss of events that may be generated while it is off doing other work and not blocked in a dciWaitEvent() call.

handleFlags contains one or more bitmapped flags which may be set to specify a buffering scheme for event metrics. If no flags are specified, no buffering is performed. The buffering scheme is on a per handle basis. The initial buffer size is system dependent but is queryable and settable using dciConfigure().

The following values may be set in handleFlags:

 

DCI_BUFFER_EVENTS_DISCARD
DCI_BUFFER_EVENTS_OVERWRITE

DCI_BUFFER_EVENTS_DISCARD and DCI_BUFFER_EVENTS_OVERWRITE instruct the DCI Server of the type of buffering policy to use for its internal event buffer. DCI_BUFFER_EVENTS_DISCARD instructs the DCI Server to drop new events when the internal event buffer is full. DCI_BUFFER_EVENT_OVERWRITE instructs the DCI Server to overwrite the oldest event(s) in the buffer when a new event arrives and the buffer is full. The internal buffer is only of importance when a consumer does not have any outstanding dciWaitEvent() requests for a particular handle. The corresponding metric identifier is ignored for this request. These two flags are mutually exclusive.

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciOpen() 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.

If the return buffer address, bufferAddress, is zero when dciOpen() is called, then dciOpen() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciOpen() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciOpen() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or metricIdList was malformed.

[DCI_BADFLAGS]

Two or more mutually exclusive flags were used together.

[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_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_NOCLASS]

No requested metric class identifier is present in the name space.

[DCI_NODATUMID]

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

[DCI_NOINSTANCE]

No requested instance identifier is present in the name space.

[DCI_NOACCESS]

There was an access permission failure for at least one request.

[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_NOTQUERYABLE]

The specified metric identifier could not be accessed.

NAME

dciPerror - produce an error message based on DCIStatus or errno

SYNOPSIS

#include <sys/dci.h>
      
void dciPerror(
    DCIStatus status,       /* in */
    int theerrno,           /* in (optional) */
    char *membuf,           /* in (optional) */
    int bufsize,            /* in */
    char *fmt, ...          /* in */
);

ARGUMENTS

status

A valid DCIStatus return value.

theerrno

The standard "_errno" (optional).

membuf

If present, the returned string is copied to this buffer.

bufsize

Maximum size in bytes of the membuf buffer.

fmt , ...

A printf format string with a variable length parameter list.

DESCRIPTION

dciPerror() will accept a DCIStatus value and lookup the corresponding text string describing the status. If the status is DCI_SYSERROR, then the argument "theerrno" is examined and the corresponding text string for that error is produced.

If membuf is supplied, then the output produced is copied to the buffer as a null terminated string up to bufsize bytes in length. If membuf is not present, the produced string is sent to stderr output.

fmt is a character string such as that used in printf(). It may include format specifiers as a variable number of arguments (up to some fixed limit). The output produced includes the formatted output for fmt and then a ":" (colon) and the text string representing the error in question.

For example, if myclassname() existed and would produce a class expressed as the symbolic character string, "datapool.mem.bufcache":

 

dciPerror(DCI_CLASSEXISTS, 0, (char *)0, 0, "Opening class %s",
   myclassname(theclass))

would produce the following on stderr:

 

Opening class datapool.mem.bufcache: 
    The DCI class is already registered.

LIMITATIONS

If membuf is not present, the string produced may be truncated to a fixed size, no smaller than 1024 bytes.

The number of arguments available to "fmt" may be limited, but that limit must be no less than 8.

RETURN VALUES

There are no return values for this routine.

NAME

dciRemoveHandleMetric - removes metrics from an open handle

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciRemoveHandleMetric(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

A handle returned from dciOpen() that has not been subsequently closed.

metricIdList

Address of a list of metric identifiers.

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.

timeout

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

DESCRIPTION

The dciRemoveHandleMetric() routine performs the inverse of dciAddHandleMetric(). It disassociates and closes a list of metrics from an open handle. Note that a metric must be deleted from a handle using the exact same metricId with which it was opened or added. For example, it is not possible to open or add a group of metrics using a wildcarded datumId and then use dciRemoveHandleMetric() to delete only a single datumId from that group. The individual datum ids should be added first, then the wildcarded datum id should be removed. Doing otherwise may result in the metric being reset when it is closed.

If the return buffer address, bufferAddress, is zero when dciRemoveHandleMetric() is called, then dciRemoveHandleMetric() allocates the return buffer on behalf of the caller and returns the buffer address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciRemoveHandleMetric() 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 dciRemoveHandleMetric() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer and the data was written to the data buffer. Otherwise, dciRemoveHandleMetric() returns one of the following fatal errors:

[DCI_NOTPRESENT]

The DCI service is not available.

[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 DCIReturn structure, or metricIdList was malformed.

[DCI_BADHANDLE]

The given handle is not valid.

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

[DCI_NODATUMID]

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

[DCI_NOINSTANCE]

One or more requested instance identifiers are not present in the handle.

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

NAME

dciSetData - request a provider to set a metric.

SYNOPSIS

#include <sys/dci.h>

DCIStatus  dciSetData(
    DCIHandle       handle,                 /* in */
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    UMAUint4        operation,              /* in */
    UMAUint4        *pConfirm,              /* in/out */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        *bufferSize,            /* in */
    void            *dataAddress,           /* in */
    UMAUint4        dataSize,               /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

handle

An open handle containing the metrics to be set.

metricIdList

Address of a list of polled metric identifiers, each of which must have been opened in the handle argument. This list specifies the subset of the handle metrics on which the set operation is to be performed. An empty list (numIds equal to zero) means that dciSetData() returns without setting any metrics.

numIds

The number of input metric identifiers in the metricIdList.

operation

This tells which operation to perform and must be one of DCI_OP_RESERVEDATA, DCI_OP_SETDATA, or DCI_OP_RELEASEDATA.

pConfirm

If operation is DCI_OP_RESERVEDATA, *pConfirm was zero, and the reservation is successful for any metric in the metricIdList, *pConfirm is set to a reservation confirmation that can be used on a successive call to dciSetData(). If *pConfirm is a valid reservation confirmation and the current reservation request is successful for any metric in the metricIdList, those metrics are added to the list of metrics covered by this confirmation. If the operation is DCI_OP_RELEASEDATA, this must contain a valid confirmation from a previous DCI_OP_RESERVEDATA operation. If the operation is DCI_OP_SETDATA and any of the metrics in the list have been reserved, *pConfirm must contain the corresponding confirmation. If none were reserved, *pConfirm must be zero.

This reservation confirmation may only be used by the process that requested it.

bufferAddress

Points to the address of a return status buffer.

bufferSize

The size of the return status buffer.

dataAddress

If operation is DCI_OP_SETDATA or DCI_OP_RESERVEDATA, this points to a buffer containing data to set.

dataSize

Size of the dataAddress buffer.

timeout

If the operation is DCI_OP_RESERVEDATA, *timeout specifies the maximum time to allow a reservation to remain valid. If the operation is DCI_OP_SETDATA, it specifies the maximum amount of time to try to set the metric. This is ignored when the operation is DCI_OP_RELEASEDATA. If metrics are added to an existing reservation confirmation, the timeout on that confirmation is reset to the timeout value from the latest call that adds metrics.

DESCRIPTION

The dciSetData() routine is used by an consumer to request that a provider set a metric to a certain value. This may be used to set configuration values for a component being managed by a specific provider.

The dciSetdata() routine facilitates setting multiple metrics in the same call and use by multiple consumers by supporting a two phase set operation using two calls to dciSetData(). The first call, with the operation set to DCI_OP_RESERVEDATA, is made to see if a set operation on a given component could occur. This asks the DCI Server to validate that setting the indicated metrics could occur with the data provided and to reserve any resources that would be required if the set command were issued. For each metric specified in this call, if the specified settings could have been made, resources are reserved, and *pConfirm is set to a special value. This special value can be used on a second call in order to validate a DCI_OP_SETDATA or DCI_OP_RELEASEDATA operation on the metrics that were just reserved. A metric that has been reserved in this manner can not be set, reserved, or released without using the respective reservation confirmation until that metric is released (using the reservation confirmation), the reservation confirmation times out, or the respective handle is closed. Also, a DCI_OP_SETDATA operation on reserved data is not guaranteed to succeed if the data is different from what was used on the previous call with DCI_OP_RESERVEDATA.

If the DCI_OP_RESERVEDATA operation is not used and multiple consumers try to set a metric, the result is indeterminate. Also, if multiple metrics are specified in a single metricIdList, some may be successfully set and others may not be. Using DCI_OP_RESERVEDATA to validate arguments and allocate resources for all metrics in a single call, before actually using DCI_OP_SETDATA, minimises the chances that when dciSetData() returns, some metrics will have been set while others will not have been set.

Resources reserved with DCI_OP_RELEASEDATA are held until a DCI_OP_SETDATA or DCI_OP_RELEASEDATA operation completes or until the timeout specified in the DCI_OP_RESERVEDATA call is exceeded. In order minimise chances for permanent deadlock, there is also an implementation specific maximum value for the reservation timeout. If a consumer makes a reservation and decides it no longer wants to set the metric, the consumer should make a dciSetData() call using the DCI_OP_RELEASEDATA operation rather than waiting for the reservation to timeout.

If dciSetData() is used to modify data for a class which supports invalid data (the DCIClassAttr flag has DCI_POSSIBLEINVALIDDATA set), the provider may reject the request with a return status of DCI_NOTSETTABLE.

If the return buffer address, bufferAddress, is zero when dciSetData() is called or if the return data buffer address, dataAddress, is zero when dciSetData() is called, then dciSetData() allocates a buffer of the correct size and places the address in bufferAddress or dataAddress respectively. If dataAddress is allocated by the library, then the size is also stored into the address provided for dataSize. The caller is then responsible for subsequently freeing the allocated memory using dciFree().

RETURN VALUES

The dciSetData() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciSetData() 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_BADCONFIRM]

The reservation confirmation is either invalid or has expired.

[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, or the operation was not recognised.

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_NOTPOLLEDMETRIC]

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

[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_NOTSETTABLE]

One or more of the associated metrics is not able to be set. This may be because the provider does not support modification of these metrics, or that an "invalid" metric was specified. The provider may choose to disallow modification of "invalid" metrics for the associated instance.

[DCI_NOTRESERVEABLE]

This metric does not support being reserved.

[DCI_RESERVED]

This metric is currently reserved by another consumer.

[DCI_NOTRESERVED]

This metric is not currently reserved so cannot be released.

[DCI_INVALIDDATA]

The associated metric is invalid for this particular class instance.

[DCI_DERIVEDDATA]

An attempt was made to set the value of a metric of type: DCI_DERIVED.

[DCI_METHODERROR]

The DCI Server has encountered an error in the method invoked to satisfy the request for the selected metric.

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

NAME

dciTerminate - terminate a connection with the Data Capture Interface

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciTerminate(void);

ARGUMENTS

"none"

DESCRIPTION

This interface is used by both metrics providers and consumers. The dciTerminate() routine allows DCI implementations to know when an application is ending a series of DCI transactions. This interface allows a DCI implementation to perform implementation specific termination. Conversely, dciInitialize() is used to perform implementation specific initialisation.

RETURN VALUES

The dciTerminate() routine returns [DCI_SUCCESS] if it was able to terminate the connection to the metric provider or consumer. Otherwise, this routine returns one of the following error values:

[DCI_NOTINITIALIZED]

The DCI subsystem is currently not initialised.

[DCI_NOTPRESENT]

The DCI service is not available.

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