All DCI functions except dciEZRegister return DCIStatus. DCIStatus returns success when a DCIRetval structure has been created. The summary status of DCIReturn and the DCIRetval structures must be checked for overall status and individual metric status. The error status value is a summary error and may not be the same for every metric in the input list. Having an error status does not imply nothing was returned. The application must traverse the DCIReturn structure to discover the status value for each metric in the input list.
The data portion of the return buffer can be a separate buffer whose storage is acquired by the DCI via vm_allocate and must be returned by the caller via dciFree, just as the return structure is. Where a dataBuffer is used, the size field in the DCIReturn structure in the status buffer does not include the size of the data area. A separate data buffer is used because volatile instances make the size of the return structure unknown until all of the data is returned for all of the instances.
The following figure shows an example of separate buffers used to return
DCIRetval, MetricId, and the output
data.
The return structure begins with a four byte integer that contains the total number of bytes written. The purpose of this size is to allow range checking and for quick traversal of multiple DCIReturn structures. The total size is followed by a count of the total number of output list identifiers. This count could differ from the input list of identifiers due to a wildcard expansion.
This header, the total size and count plus the summary status is followed by two arrays. The first is an array of count DCIRetval structures, one for each expanded metric or class identifier. The DCIRetval structure gives the return status, a count of the number of returned data items for the request (which is set to 1 due to one Retval per metricid/classid expansion), an offset to the metric identifier or class identifier which may have been expanded from a wildcard if supported by the command, and an offset to the output data for this request. The metric identifier is an offset from the beginning of the DCIReturn, and the data offset is an offset from the beginning of dataBuffer structure when a separate data buffer is used (otherwise it's an offset from the beginning of DCIReturn). Note that the DCIRetval structure is a fixed size allowing for quick traversal of the DCIRetval array.
Following the array of DCIRetval structures is the metric identifier or class identifier which may have been expanded from a wildcard if supported by the command. Some DCI routines, take class identifier lists as input while others take full metric identifiers as input. Applications acquire offsets into these structures by traversing the DCIRetval array.
Some routines may not return data. In this case there is no returned data buffer and the area in the DCIReturn structure and the count and dataOffset fields of the DCIRetval structure are unused and their values are set to zero. Clearing these fields prevents applications which inadvertently ignore status values from access memory outside of the input buffer range.