IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]


14.3 Invalid Data

In order to support the elimination of unwanted items from a data set, positions, connections, faces, or polylines in a Field can be "invalidated" by placing a corresponding "invalid positions," "invalid connections," "invalid faces," or "invalid polylines" component in that Field. An "invalid" component lists the individual data items of the positions, connections, faces, or polylines component that are invalid.

In position-, connection-, face-, and polyline-dependent components, data items that correspond to invalid elements are themselves invalid. Data may be invalidated by modifying (or creating, if necessary) these invalid components. If no invalid component exists, all data items are assumed to be valid.

An invalid component is represented by one of two types of Array:

  1. An Array of length equal to the length of the "positions," "connections," "faces," or "polylines" component. This component has the "dep" attribute of "positions," "connections," "faces," or "polylines" (i.e., the elements correspond one-to-one with the elements in the applicable Array). The Array is either TYPE_BYTE or TYPE_UBYTE; its valid elements have a value of DATA_VALID (0), invalid elements a value of DATA_INVALID (1).

  2. An Array of length equal to the number of invalid members of the applicable component. This component has the "ref" attribute of "positions," "connections," "faces," or "polylines." The Array is either TYPE_INT or TYPE_UINT, and the indices of the invalid members are listed.

If many elements of the component are invalid, the first type of Array is preferable. If only a few elements are invalid, the second is preferable.

The routines described here simplify the handling of both types of invalid component.

Once positions have been invalidated, their immediate connections, faces, or polylines can also be invalidated by calling DXInvalidateConnections(), which will create an "invalid connections," "invalid faces," or "invalid polylines" component if necessary. (Note that this component cannot be assumed to be up-to-date unless this routine is called.)

Invalid positions, connections, faces, and polylines (and their dependent information) can be removed from the data set by calling DXCull(). This routine:

Removal of invalid components may affect system performance significantly if it requires the conversion of regular positions and connections components to irregular form (i.e., by greatly increasing the memory used for these components). For example, DXCreateInvalidComponentHandle() creates a "handle" for a specified invalid component. Other routines set particular elements as valid or invalid or they determine the validity of a given element. The module writer can set up a handle to mark elements as either valid or invalid (e.g., initializing all elements to invalid and validating the appropriate elements or vice versa).

When the time comes to create an invalid-component Array, the information stored in the handle is used to create one of the two kinds of Array just described, depending on the relative number of invalid elements.

Note: Before adding a new invalid component to a Field, it is important to explicitly remove any invalid component having the same name. The reason for this requirement is that the attributes of an existing component will be copied to the new component. Overwriting a "dep" invalid component with a "ref" invalid component will result in a component with both attributes, which is self-contradictory.

#define DATA_VALID   0
#define DATA_INVALID 1

Object DXInvalidateConnections()

Propagates the invalidity of positions. See DXInvalidateConnections.

Object DXInvalidateDupBoundary()

Invalidates all but one of the positions shared between partitions in a Composite Field. See DXInvalidateDupBoundary.

Object DXInvalidateUnreferencedPositions()

Determines which positions in the Fields of the input Object are not referenced by any connections element and invalidates them. See DXInvalidateUnreferencedPositions.

Object DXCull()

Removes invalid positions and connections (and their dependent information) from an Object. See DXCull.

InvalidComponentHandle DXCreateInvalidComponentHandle()

Creates an invalid-component handle. See "Examples". See DXCreateInvalidComponentHandle.

Error DXFreeInvalidComponentHandle()

Frees all memory associated with an invalid-component handle. See DXFreeInvalidComponentHandle.

Error DXSaveInvalidComponent()

Creates a new invalid-component Array containing the information stored in an invalid-component handle and stores it in a given Field. See "Examples". See DXSaveInvalidComponent.

Array DXGetInvalidComponentArray()

Returns an Array containing the information stored in an invalid-component handle. See DXGetInvalidComponentArray.

Error DXSetElementValid()

Sets the validity state of a specified element in an invalid-component handle to DATA_VALID. See DXSetElementValid.

Error DXSetElementInvalid()

Sets the validity state of a specified element in an invalid-component handle to DATA_INVALID. See "Examples". See DXSetElementInvalid.

int DXIsElementValid()
int DXIsElementInvalid();

Return the validity state of a specified element of an invalid-component handle. See "Examples". See DXIsElementValid, DXIsElementInvalid.

int DXIsElementValidSequential()
int DXIsElementInvalidSequential();

Return the validity state of a specified element of an invalid-component handle when the queries come in sequential order. See DXIsElementValidSequential, DXIsElementInvalidSequential.

int DXGetValidCount()

Returns the number of valid elements in an invalid-component handle. See DXGetValidCount.

int DXGetInvalidCount()

Returns the number of invalid elements in an invalid-component handle. See DXGetInvalidCount.

Error DXSetAllValid()

Sets all elements valid. See DXSetAllValid.

Error DXSetAllInvalid()

Sets all elements invalid. See "Examples". See DXSetAllInvalid.

Error DXInvertValidity()

Reverses the validity state of every element in a specified invalid-component handle. See DXInvertValidity.

Error DXInitGetNextInvalidElementIndex()
Error DXInitGetNextValidElementIndex();

Prepare an invalid-component handle for iteration through the invalid or valid elements. See DXInitGetNextInvalidElementIndex, DXInitGetNextValidElementIndex.

int DXGetNextInvalidElementIndex()

Returns the index of the next invalid element after the index returned on the previous call. See DXGetNextInvalidElementIndex.

int DXGetNextValidElementIndex()

Returns the index of the next valid element after the index returned on the previous call. See DXGetNextValidElementIndex.

Examples

Invalid-component handles have a variety of uses, as shown in these examples.


[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page]


[IBM Home Page | Order | Search | Contact IBM | Legal ]