Data Capture Interface (DCI) - Metrics Provider Routines

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

Metrics Provider Routines

This Chapter describes the interfaces used by metrics providers. Data Capture Interface (DCI) - dciAddInstance Previous section.

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

NAME

dciAddInstance - add an instance to a metric class

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciAddInstance(
    DCIClassId       *classId,               /* in */
    DCIInstanceId    *instanceId,            /* in */
    DCIInstAttr      *instAttr,              /* in */
    DCIMethod        *method,                /* in */
    DCIReturn        **bufferAddress,        /* in/out */
    UMAUint4         bufferSize              /* in */
);

ARGUMENTS

classId
Address of a single classId to add instance to. This may not contain any wildcards.

instanceId
Address of an instance identifier to be added to the class. This may not contain any wildcards.

instAttr
Address of an instance attribute corresponding to the instance identifier being added. If this is zero, an attribute with a zero length label and zero sized extended attributes is created for the instance.

method
Address of an instance method corresponding to the instance identifier being added. If this is zero, no instance method is added and there must be a class method already registered for the given class.

bufferAddress
Points to the address of a return value buffer. If the address pointed to is zero, the system allocates a buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciAddInstance() routine adds an instance to a class. This routine takes as input an instance identifier (instanceId), and optionally, an attribute structure (instAttr) or method structure (method) that correspond with the instance identifiers.
The instance attribute specified in instanceAttr can be retrieved by a consumer using dciGetInstAttributes(). The method allows a provider to specify a method to be used instead of a class method registered with the class. (Instances with and without methods can be mixed in a class.)
The DCI_ADDRESS and DCI_CALLBACK instance method types are dependent on the address space of the provider who issues the dciAddInstance() being available to the DCI Server. If the address space of such a provider with instances that have not been removed becomes unavailable, such as when the provider terminates, any instances registered with dciAddInstance() is implicitly removed. On a related note, if the address space of a class which has a class method of type DCI_ADDRESS or DCI_CALLBACK becomes unavailable to the DCI Server, the entire class is implicitly unregistered.
Class instances for which the DCI_STORE instance method is in effect must submit initial data in the DCIReturn structure bufferAddress. The data in the structure must conform to the previously registered attributes structure. All datum identifiers of the metric identifiers in the DCIReturn structure should be wildcarded and the corresponding data section should contain all class data of the specified class instance(s), with an offset as specified in the previously registered attributes structure. None of the other identifiers can be wildcarded.
If the return buffer address, bufferAddress, is zero when dciAddInstance() is called, then dciAddInstance() 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 dciAddInstance() routine returns [DCI_SUCCESS] if all requested metric instances can be registered in the name space and the standard DCI return structure can be written into the output buffer. Otherwise, this routine returns one of the DCI error values to summarise the failure type.
A failure causes one of the following to be returned. These are summary errors. If the request consisted of multiple metrics then the return buffer status field should be examined to determine which metrics failed.

[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_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 MethodList 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_INSTANCEEXISTS]
This instance could not be added because it already exists.

[DCI_NOWILDCARD]
A class or instance wildcard cannot be used in this context.

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

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

[DCI_INVALIDMETHODOP]
The operation specified is not a valid operation.

[DCI_INVALIDFIELD]
The associated DCIMethod attributes structure was malformed.

[DCI_NOTEXT]
No label has been specified with DCIInstanceAttr field of the DCIMethod.

[DCI_INSTANCENOTPERSISTENT]

If the parent class is not persistent and the new DCIInstAttr specifies persistence.

[DCI_BADFLAGS]
If persistence is defined for the DCIInstAttr, but the method type is DCI_ADDRESS or DCI_CALLBACK.

[DCI_NOCLASS]
The specified metric class identifier is not present in the name space.

[DCI_NOACCESS]
The caller does not have permission to add an instance to this class.

Data Capture Interface (DCI) - dciPostData Previous section.

NAME

dciPostData - post polled data, instance data, or configuration data

SYNOPSIS


#include <sys/dci.h>
DCIStatus dciPostData(
    UMAUint4     operation,              /* in */
    UMAUint4     transactionId,          /* in */
    DCIReturn    *status,                /* in */
    void         *data,                  /* in */
    UMAUint4     dataSize,               /* in */
    DCIReturn    **bufferAddress,        /* in/out */
    UMAUint4     bufferSize              /* in */
);

ARGUMENTS

operation
The type of operation. Must be one of the values possible in the operation field of the DCIMethod struct.

transactionId
The identifier of the transaction associated with this data post.

status
Address of a DCIReturn structure listing the metric identifiers and data offsets.

data
Address of the data buffer.

dataSize
Size of the data buffer in bytes.

bufferAddress
Points to the address of a return value buffer. If the address pointed to is zero, the system allocates a buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciPostData() routine is used by a provider for transmitting a list of polled data, instance data, configuration data or status values in response to a consumer request. The provider supplies the type of operation, which determines the type of data returned in the DCIReturn structure status and data buffer. The provider writes a DCIReturn structure to the status parameter which lists the metric identifiers and related data offsets. The data buffer may be filled with data corresponding to the operation. The status DCIReturn structure combined with the data buffer is used to fulfill a consumer's request.
If the operation is DCI_OP_GETDATA the supplied data must conform to the previously registered attributes structure. Although the DCI Server cannot verify the content of the data, it verifies that the size matches the registered attributes. Only datum identifier wildcards are allowed, in which case all instantiated class data is returned within a single data section.
If the operation is DCI_OP_CONFIGURE the supplied data must contain DCIConfig structures, one or more per metric identifier depending on the number of encoded instance identifiers.
If the operation is DCI_OP_LISTINSTANCES the supplied metric identifiers must have expanded instance identifiers. The data buffer is unused. The datum identifiers are ignored.
If the operation is DCI_OP_GETINSTATTR the supplied metric identifiers may have expanded instance identifiers and the supplied data must contain DCIInstAttr structures, one or more per metric identifier, identifying each instantiated metric class. The datum identifiers are ignored.
If the operation is DCI_OP_SETDATA, DCI_OP_RESERVEDATA or DCI_OP_RELEASEDATA only the status information is used; the data buffer is unused.
The transactionId is used to alert the DCI Server as to the ultimate DCI consumer for this data. For DCI_WAIT method classes, the transactionId was returned from the associated dciWaitRequest(). For classes not using DCI_WAIT, the transactionId is not relevant and must be set to 0.
When the dciPostData() returns, the DCIReturn structure bufferAddress contains return status' for all submitted metric identifiers.
If the return buffer address, bufferAddress, is zero when dciPostData() is called, then dciPostData() 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 dciPostData() routine returns [DCI_SUCCESS] if all requested metric instances can be submitted to the DCI Server. Otherwise, this routine returns one of the DCI error values to summarise the failure type.

[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_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 methodList 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_NOINSTANCE]
The requested instance identifier is not in the name space.

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

[DCI_NOMETRIC]
There is no such metric identifier in the name space.

[DCI_NOSUCHTRANSACTION]
The transactionId was either invalid or the associated transaction was no longer active.

[DCI_NOWILDCARD]
A class or instance wildcard cannot be used in this context.

Data Capture Interface (DCI) - dciRegister Previous section.

NAME

dciRegister - register a metric class

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciRegister(
    DCIClassId      *classId,               /* in */
    DCIClassAttr    *classAttr,             /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize              /* in */
);

ARGUMENTS

classId
Address of a DCIClassId structure.

classAttr
Address of a DCIClassAttr structure.

bufferAddress
Points to the address of a return value buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciRegister() routine allows providers to create a new class in the name space. For the specified DCIClassId element in classIdList, there must be a corresponding DCIClassAttr structure which establishes the definition of the new class; information such as the number of instance levels and their types and well as the label and type of all datum metrics which are provided. The DCIClassId must be fully specified without the use of class wildcards.
If the return buffer address, bufferAddress, is zero when dciRegister() is called, then dciRegister() 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().
Upon return dciRegister() fills the return buffer specified by bufferAddress with a DCIReturn structure. For the input DCIClassId, there is a corresponding DCIRetval structure produced in the return buffer. The metricOffset field of the DCIRetval specifies an offset from the buffer specified by bufferAddress and contains the DCIClassId associated with the status field of the DCIRetval structure. The dataOffset field is set to 0.

RETURN VALUES

The dciRegister() routine returns [DCI_SUCCESS] if the DCIReturn structure could be written. Otherwise, dciRegister() 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_INVALIDARG]
One of the input arguments is invalid: numIds was 0, bufferSize is smaller than the size of a DCIReturn structure, classIdList was malformed or classAttrList was malformed.

[DCI_INVALIDFIELD]
One of the argument structure fields was not acceptable. This result will occur if a UMA_DERIVED DCIDataAttr is presented with a nonzero method flags argument.

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. This is only returned if any class other than the deepest specified class is not in the namespace.

[DCI_NOWILDCARD]
A wildcard cannot be used in this context.

[DCI_INVALIDFIELD]
The associated DCIClassAttr structure has an invalid field.

[DCI_CLASSEXISTS]
This class could not be registered because it already exists.

[DCI_CLASSNOTPERSISTENT]
If the parent class is not persistent, and the new DCIClassAttr specifies persistence.

[DCI_BADFLAGS]
If persistence is defined for a DCIClassAttr, but the method type is DCI_ADDRESS or DCI_CALLBACK.

[DCI_NOACCESS]
The caller does not have permission to register this class.

[DCI_NOTEXT]
No label has been specified in the DCIClassAttr field of this class.

Data Capture Interface (DCI) - dciRemoveInstance Previous section.

NAME

dciRemoveInstance - removes instances from a metric class

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciRemoveInstance(
    DCIMetricId     *metricId,              /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize              /* in */
);

ARGUMENTS

metricId
Address of a DCIMetricId structure.

bufferAddress
Points to the address of a return value buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciRemoveInstance() routine removes the specified instances from the metrics name space. This routine takes as input an address of a DCIMetricId structure. The associated instances are removed from the name space. If so configured, this leads to a "final data" notification to all interested DCI consumers which have any removed instance open. The datumId field of the DCIMetricId is ignored. Upon return, dciRemoveInstance() produces DCIReturn structure at the address pointed to by bufferAddress. Each DCIRetval structure within the DCIReturn structure reflects the status of each instance removed. The metricOffset member of each DCIRetval specifies a location relative to bufferAddress and references the DCIMetricId structure. The dataOffset member is zero.
If the return buffer address, bufferAddress, is zero when dciRemoveInstance() is called, then dciRemoveInstance() 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 dciRemoveInstance() routine returns [DCI_SUCCESS] if the DCIReturn structure was written into the output buffer. Otherwise, dciRemoveInstance() 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 was requested to provide memory for the specified buffer and could not. The application could attempt to allocate its own memory and try the request again.

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

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

[DCI_FAILURE]
There was at least one failure status.

[DCI_WARNING]
There was at least one warning status and no failure status.

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

[DCI_SUCCESS]
All status returned was successful.

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

[DCI_SUCCESS]
The request succeeded and there may be associated data.

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

[DCI_NOINSTANCE]
The requested instance identifier is not in the name space.

[DCI_NOACCESS]
The caller does not have permission to remove an instance from this class.

Data Capture Interface (DCI) - dciSetClassAccess Previous section.

NAME

dciSetClassAccess - sets access control for metric classes

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciSetClassAccess(
    DCIClassId      *classIdList,           /* in */
    DCIAccess       *accessList,            /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize              /* in */
);

ARGUMENTS

classIdList
Address of a list of metric class identifiers.

accessList
A list of access control structures, one for each input metric class identifier.

numIds
The number of input metric class identifiers.

bufferAddress
Points to the address of a return value buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciSetClassAccess() routine allows a provider to set the access control for a list of class identifiers. The access control information is initially set when classes are registered. This routine allows subsequent modification of the access control structure. There is no requirement that restricting access disables those consumers which have previously opened the metrics class but some secure implementations may enforce this behaviour.
If the return buffer address, bufferAddress, is zero then dciSetClassAccess() allocates the return buffer on behalf of the caller and return its address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory. Upon return dciSetClassAccess() writes the standard DCIReturn structure into the status buffer.

RETURN VALUES

The dciSetClassAccess() routine returns [DCI_SUCCESS] if all requested metric identifiers are in the name space, the caller has permission to set their access, and the standard DCI return structure can be written into the output buffer. Otherwise, this routine returns one of the DCI error values to summarise the failure type.
A failure causes one of the following to be returned. These are summary errors. If the request consisted of multiple classes then the return buffer status field should be examined to determine which classes failed.

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

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

[DCI_FAILURE]
There were multiple but different failure types for the requested metric identifiers.

[DCI_NOCLASS]
Any requested metric class identifier is not present in the name space.

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

[DCI_NOSPACE]
The size of the given return buffer is smaller than needed. A partial write of the results may have been performed.
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_NOSUPPORT]
The implementation does not support this interface.

The possible status values written into the DCIReturn status field are:

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

[DCI_NOACCESS]
The caller does not have permission to modify access control.

[DCI_NOSPACE]
There was not enough room in the return buffer to write the expanded metric values for the requested instance identifier.
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.

Data Capture Interface (DCI) - dciSetInstAccess Previous section.

NAME

dciSetInstAccess - sets access control for metric instances

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciSetInstAccess(
    DCIMetricId     *metricIdList,          /* in */
    DCIAccess       *accessList,            /* in */
    UMAUint4        numIds,                 /* in */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

metricIdList
Address of a list of metric class and instance identifiers.

accessList
A list of access control structures, one for each input instance identifier.

numIds
The number of input instance identifiers.

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, dciSetInstAccess() blocks indefinitely.

DESCRIPTION

The dciSetInstAccess() routine allows a provider to set the access control for a list of instance identifiers. The access control information is initially set when instances are added to the name space. This routine allows subsequent modification of the access control structure. There is no requirement that restricting access disables those consumers which have previously opened an instance but some secure implementations may enforce this behaviour.
The access control value of intermediate instance levels in a multiple level instance structure can be set by limiting the input instance value to the desired level. For example, if one wanted to set the access control field on the first instance level in a two level structure then only use the first level as the instance argument in metricIdList.
The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciSetInstAccess() 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 then dciSetInstAccess() allocates the return buffer on behalf of the caller and return its address in bufferAddress. The caller is then responsible for subsequently freeing the allocated memory. Upon return dciSetInstAccess() writes the standard DCIReturn structure into the status buffer.

RETURN VALUES

The dciSetInstAccess() routine returns [DCI_SUCCESS] if all requested metric identifiers are in the name space, the caller has permission to set their access, and the standard DCI return structure can be written into the output buffer. Otherwise, this routine returns one of the DCI error values to summarise the failure type.
A failure causes one of the following to be returned. These are summary errors. If the request consisted of multiple classes then the return buffer status field should be examined to determine which classes failed.

[DCI_NOTINITIALIZED]
The DCI subsystem is 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.

[DCI_INVALIDARG]
One of the input arguments is invalid.

[DCI_FAILURE]
There were multiple but different failure types for the requested metric identifiers.

[DCI_NOCLASS]
Any requested metric class identifier is not present in the name space.

[DCI_NOINSTANCE]
Any requested instance identifier is not present in the name space.

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

[DCI_NOSPACE]
The size of the given return buffer is smaller than needed. A partial write of the results may have been performed.
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_NOSUPPORT]
The implementation does not support this interface.

[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 possible status values written into the DCIReturn status field are:

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

[DCI_NOINSTANCE]
Any requested instance identifier is not present in the name space.

[DCI_NOACCESS]
The caller does not have permission to modify access control.

[DCI_NOSPACE]
There was not enough room in the return buffer to write the expanded metric values for the requested instance identifier.
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_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.

Data Capture Interface (DCI) - dciUnregister Previous section.

NAME

dciUnregister - unregister a metric class.

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciUnregister(
    DCIClassId    *classId,               /* in */
    DCIReturn     **bufferAddress,        /* in/out */
    UMAUint4      bufferSize              /* in */
);

ARGUMENTS

classId
Address of a DCIClassId structure.

bufferAddress
Points to the address of a return value buffer.

bufferSize
The size of the return buffer.

DESCRIPTION

The dciUnregister() routine allows providers to remove one of their registered classes from the namespace. This routine takes as input the address of a DCIClassId structure. The DCIClassId may include the class identifier wildcard value, DCI_ALL. For each DCIClassId in the array, the class is unregistered and removed from the namespace.
If the return buffer address, bufferAddress, is zero when dciUnregister() is called, then dciUnregister() 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 dciUnregister() routine returns [DCI_SUCCESS] if the DCIReturn structure could be written. Otherwise, dciUnregister() 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 was requested to provide memory for the specified buffer and could not. The application could attempt to allocate its own memory and try the request again.

[DCI_INVALIDARG]
One of the input arguments is invalid: numIds was 0, 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_NOCLASS]
The requested metric class identifier is not present in the name space.

[DCI_CLASSNOTEMPTY]
The class could not be removed because either there are subclasses still registered, or instances still defined for this class.

[DCI_NOACCESS]
The caller does not have permission to unregister this class.

Data Capture Interface (DCI) - dciWaitRequest Previous section.

NAME

dciWaitRequest - wait for service request

SYNOPSIS

#include <sys/dci.h>

DCIStatus dciWaitRequest(
    DCIMetricId     *metricIdList,          /* in */
    UMAUint4        numIds,                 /* in */
    UMAUint4        *operation,             /* out */
    UMAUint4        *transactionId,         /* out */
    DCIReturn       **bufferAddress,        /* in/out */
    UMAUint4        bufferSize,             /* in */
    UMATimeVal      *timeout                /* in */
);

ARGUMENTS

metricIdList
Address of a list of DCIMetricId structures.

numIds
The number of DCIMetricId structures in metricIdList.

operation
The type of operation. Must be one of the values possible in the operation field of the DCIMethod struct.

transactionId
Address of a memory location into which the associated transactionId is stored on a successful return from dciWaitRequest().

bufferAddress
Points to the address of a return value buffer. If the address pointed to is zero, the system allocates a 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, dciWaitRequest() blocks indefinitely.

DESCRIPTION

The dciWaitRequest() routine allows a metrics provider to synchronously wait for a metrics service request. The dciWaitRequest() returns when a consumer requests the provider's metrics using dciGetData(), alters metrics using dciSetData(), lists instances with dciListInstanceId(), requests instance attributes with dciGetInstAttributes(), or configures metrics using dciConfigure().
The dciWaitRequest() announces the metrics it can serve by providing the metricIdList. The metric identifiers in this list should correspond to the way the provider registered itself. If the provider registered DCI_WAIT as a class method, it can use a wildcard at the instance level, otherwise it can only use wildcards at the datum level
When dciWaitRequest() returns, the operation contains the operation requested by the DCI Server, and the bufferAddress contains a DCIReturn structure with the requested metricIds. The transactionId returned is to be used as an input argument for all associated dciPostData() responses to ensure that the data sent will be properly directed to a waiting consumer. If data is supplied it is encoded in the DCIReturn structure with data offsets from the beginning of the DCIReturn structure.
If the operation is DCI_OP_GETDATA or DCI_OP_RELEASEDATA, only metric identifiers are supplied in the DCIReturn structure. Datum wildcarding may be used. If the class is not DCI_PROVIDER_INSTANCE, instance identifier can not be wildcarded.
If the operation is DCI_OP_LISTINSTANCES, only metric identifiers are supplied in the DCIReturn structure, of which the datum identifier should be ignored. The instance identifiers can be wildcarded.
If the operation is DCI_OP_GETINSTATTR, only metric identifiers are supplied in the DCIReturn structure, of which the datum identifier should be ignored. The instance identifiers can be wildcarded.
If the operation is DCI_OP_CONFIGURE, data is supplied in the DCIReturn structure in addition to the metric identifiers. Each data section contains one or more DCIConfig structures, depending on the number of instance identifiers encoded in the corresponding metric identifier. The instance identifier can be zero length which indicates "all current and future instances". Only datum identifier wildcards are allowed, unless the class is a DCI_PROVIDER_INSTANCES class in which case instance identifier wildcards are allowed.
If the operation is DCI_OP_SETDATA or DCI_OP_RESERVEDATA, data is supplied in the DCIReturn structure in addition to the metric identifiers. This data conforms to the previously registered attributes structure. Only datum identifier wildcards are allowed, unless the class is a DCI_PROVIDER_INSTANCES class in which case instance identifier wildcards are allowed.
The timeout parameter points to a type UMATimeVal structure that specifies the maximum time to wait for the completion of the dciWaitRequest() 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 dciWaitRequest() is called, then dciWaitRequest() 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 dciWaitRequest() routine returns [DCI_SUCCESS] if the DCI Server successfully placed a request. Otherwise, this routine returns one of the DCI error values to summarise the failure type.

[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 was requested to provide memory for the specified buffer and could not. The application could attempt to allocate its own memory and try the request again.

[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 methodList 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_NODATUMID]
The associated metricId specified a nonexistent datumId for the specified class.

[DCI_NOMETRIC]
There is no such metric identifier in the name space.

[DCI_NOWILDCARD]
A class or instance wildcard cannot be used in this context.

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

Contents

Next section

Index