Device Class Definitions for the Upgrade Front-End Project

Functions for the Device class and its sub-classes

Include files for Device class object definitions
Types Declared for Device class objects
Device Superclass
- devInitialize - Initialize a Device Object
- devGetIndex - Get the Index of a Device Object
- devGetType - Get the Type of a Device Object
Distribution Class
- dstAddPoint - Add a New Point to a Distribution Object
- dstClassCreate - Create the Distribution Class Context
- dstClassDelete - Delete the Distribution Class Context
- dstClear - Clear a Distribution Object
- dstCreate - Create a New Distribution Object
- dstDelete - Delete an Existing Distribution Object
- dstGetMean - Get the Mean of a Distribution Object
- dstGetMoments - Get the Moments of a Distribution Object
- dstGetVariance - Get the Variance of a Distribution Object
- dstShow - Show the Contents of a Distribution Object
Histogram Class
- hstAddPoint - Add a New Point to a Histogram Object
- hstClear - Clear a Histogram Object
- hstCreate - Create a New Histogram Object
- hstDelete - Delete an Existing Histogram Object
- hstGetCells - Get the Cumulative Cell Counts of a Histogram Object
- hstGetMean - Get the Mean of a Histogram Object
- hstGetMoments - Get the Moments of a Histogram Object
- hstGetParameters - Get the Parameters of a Histogram Object
- hstGetVariance - Get the Variance of a Histogram Object
- hstShow - Show the Contents of a Histogram Object

Include files for Device class object definitions

To incorporate the Device class definitions in your C source file you must have the following statement line in that file:

#include "device_class.h"

This will define all of the data types and functions which are required to access objects of the Device class and their methods (functions).

Types Declared for Device class objects

DvIdentifier

Structure containing a device identifier (four bytes in the current implementation)

DvType

Enumerated type designating the type (subclass) of device

memDevType - Memory access
distDevType - Distribution
histDevType - Histogram

DvIndex

Integer designating the instance of the device

DvStatus

Status returned by device class procedures

DVS_SUCCESS - The function completed with no errors
DVS_EMPTY - The device is in its initial state
DVS_FAIL - The function could not complete (see the routine description for details)
DVS_INVALID_ID - The identifier does not refer to a valid device
DVS_NO_IDENTIFIERS - No more identifiers are available for this device class or its sub-classes
DVS_NO_MEMORY - There is no dynamic memory available to allocate the device structure
DVS_BAD_ARGUMENT - One of the arguments has a value which is outside the acceptable range
DVS_ARRAY_TOO_SMALL - An array was too small to contain all of the required elements

Device Superclass Functions

Function devInitialize - Initialize a Device Object

Usage Template:: DvIdentifier devInitialize(const DvDevice *device, const DvType type, unsigned int index)
Description:
Inputs:: device - Device object structure
type - Device class type
index - Device class index
Outputs:: none
Returns:: DvIdentifier - Device identifier

Function devGetIndex - Get the Index of a Device Object

Usage Template:: unsigned int devGetIndex(const DvIdentifier devId)
Description:
Inputs:: devId - Device identifier
Outputs:: none
Returns:: DvIndex - Device class index

Function devGetType - Get the Type of a Device Object

Usage Template:: DvType devGetType(const DvIdentifier devId)
Description:
Inputs:: devId - Device identifier
Outputs:: none
Returns:: DvType - Device class type

Distribution Device Class Functions

Function dstAddPoint - Add a New Point to a Distribution Object

Usage Template:

DvStatus dstAddPoint(const DvIdentifier distId, const float
          value)

Description:

Inputs:

distId - Distribution object identifier
value - Value of the new point

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the value was added to the distribution object
DVS_INVALID_ID if the identifier is not valid

Function dstClassCreate - Create the Distribution Class Context

Usage Template:

DvStatus dstClassCreate(const unsigned int maxIds)

Description:

Inputs:

maxIds - Maximum number of class members (instances)

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the class context was created
DVS_FAIL if the class context already exists
DVS_NO_MEMORY if the class context structure could not be allocated

Function dstClassDelete - Delete the Distribution Class Context

Usage Template:

DvStatus dstClassDelete(void)

Description:

Inputs:

none

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the class context was deleted
DVS_FAIL if the class context does not exist

Function dstClear - Clear a Distribution Object

Usage Template:

DvStatus dstClear(const DvIdentifier distId)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the distribution was set to its cleared (initial) state
DVS_INVALID_ID if the identifier is not valid

Function dstCreate - Create a New Distribution Object

Usage Template:

DvStatus dstCreate(DvIdentifier *distId)

Description:

Inputs:

none

Outputs:

distId - Distribution object identifier

Returns:

DvStatus:

DVS_SUCCESS if the object was created
DVS_NO_IDENTIFIERS if there were no free identifiers
DVS_NO_MEMORY if the object structure could not be allocated

Function dstDelete - Delete an Existing Distribution Object

Usage Template:

DvStatus dstDelete(const DvIdentifier distId)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the distribution object resources were released
DVS_INVALID_ID if the identifier is not valid

Function dstGetMean - Get the Mean of a Distribution Object

Usage Template:

DvStatus dstGetMean(const DvIdentifier distId, float *mean)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

mean - First moment of the distribution

Returns:

DvStatus:

DVS_SUCCESS if the distribution moments were evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the distribution is empty

Function dstGetMoments - Get the Moments of a Distribution Object

Usage Template:

DvStatus dstGetMoments(const DvIdentifier distId, float *count, float
          *mean, float *variance)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

count - Pointer to count of points in the distribution
mean - Pointer to first moment of the distribution
variance - Pointer to second central moment of the distribution

Returns:

DvStatus:

DVS_SUCCESS if the distribution moments were evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the distribution is empty

Function dstGetVariance - Get the Variance of a Distribution Object

Usage Template:

DvStatus dstGetVariance(const DvIdentifier distId, float
          *variance)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

variance - Pointer to second central moment of the distribution

Returns:

DvStatus:

DVS_SUCCESS if the distribution variance was evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the distribution is empty

FunctiondstShow - Show the Contents of a Distribution Object

Usage Template:

DvStatus dstShow(const DvIdentifier distId)

Description:

Inputs:

distId - Distribution object identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the distribution object was printed
DVS_INVALID_ID if the identifier is not valid

Histogram Device Class Functions

Function hstAddPoint - Add a New Point to a Histogram Object

Usage Template:

DvStatus hstAddPoint(const DvIdentifier histId, const float
          value)

Description:

Inputs:

histId - Histogram object identifier
value - Value of the new point

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the value was added to the histogram object
DVS_INVALID_ID if the identifier is not valid

Function hstClear - Clear a Histogram Object

Usage Template:

DvStatus hstClear(const DvIdentifier histId)

Description:

Inputs:

histId - Histogram identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the histogram was set to its cleared (initial) state
DVS_INVALID_ID if the identifier is not valid

Function hstCreate - Create a New Histogram Object

Usage Template:

DvStatus hstCreate(DvIdentifier *histId, unsigned int cellCount,
          float loLimit, float hiLimit)

Description:

Inputs:

cellCount - Number of histogram cells
loLimit - Lower limit of the histogramming range
hiLimit - Upper limit of the histogramming range

Outputs:

histId - Histogram identifier

Returns:

DvStatus:

DVS_SUCCESS if the header was initialized
DVS_NO_IDENTIFIERS if there were no free identifiers
DVS_NO_MEMORY if the histogram structure could not be allocated
DVS_BAD_ARGUMENT if the number of histogram cells was too large

Function hstDelete - Delete an Existing Histogram Object

Usage Template:

DvStatus hstDelete(const DvIdentifier distId)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the histogram object resources were released
DVS_INVALID_ID if the identifier is not valid

Function hstGetCells - Get the Cumulative Cell Counts of a Histogram Object

Usage Template:

DvStatus hstGetCells(const DvIdentifier histId, const unsigned int
          size, unsigned short int cells[], unsigned int *length, unsigned
          short int *underflow, unsigned short int *overflow)

Description:

Inputs:

histId - Histogram object identifier
size - Size of cell array (in units of short int)

Outputs:

cells - Array of cell counts
length - Number of cells written to the cell array (optional)
underflow - Counts in the underflow cell (optional)
overflow - Counts in the overflow cell (optional)

Returns:

DvStatus:

DVS_SUCCESS if the histogram mean was evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the histogram is empty
DVS_ARRAY_TOO_SMALL if the output array was too small to contain all of the histogram cells

Function hstGetMean - Get the Mean of a Histogram Object

Usage Template:

DvStatus hstGetMean(const DvIdentifier distId, float *mean)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

mean - Pointer to first moment of the histogram

Returns:

DvStatus:

DVS_SUCCESS if the histogram mean was evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the histogram is empty

Function hstGetMoments - Get the Moments of a Histogram Object

Usage Template:

DvStatus hstGetMoments(const DvIdentifier distId, float *count, float
          *mean, float *variance)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

count - Pointer to count of points in the histogram
mean - Pointer to first moment of the histogram
variance - Pointer to second central moment of the histogram

Returns:

DvStatus:

DVS_SUCCESS if the histogram moments were evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the histogram is empty

Function hstGetParameters - Get the Parameters of a Histogram Object

Usage Template:

DvStatus hstGetParameters(const DvIdentifier histId, unsigned int
          *cellCount, float *loLimit, float *hiLimit)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

cellCount - Number of histogram cells
loLimit - Lower limit of the histogramming range
hiLimit - Upper limit of the histogramming range

Returns:

DvStatus:

DVS_SUCCESS if the histogram mean was evaluated
DVS_INVALID_ID if the identifier is not valid

Function hstGetVariance - Get the Variance of a Histogram Object

Usage Template:

DvStatus hstGetVariance(const DvIdentifier distId, float
          *variance)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

variance - Pointer to second central moment of the histogram

Returns:

DvStatus:

DVS_SUCCESS if the histogram mean was evaluated
DVS_INVALID_ID if the identifier is not valid
DVS_EMPTY if the histogram is empty

Function hstShow - Show the Contents of a Histogram Object

Usage Template:

DvStatus hstShow(const DvIdentifier distId)

Description:

Inputs:

histId - Histogram object identifier

Outputs:

none

Returns:

DvStatus:

DVS_SUCCESS if the histogram moments were evaluated
DVS_INVALID_ID if the identifier is not valid

jfb

Last updated: 23-Feb-1995