# 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:

- Removes all invalidated elements and the corresponding elements of components that are dependent on invalidated elements.
- Renumbers components that reference positions, connections, faces, and polylines (inserting a -1 for indices that refer to removed positions, connections, faces, and polylines).
- Removes invalid positions, invalid connections, invalid faces, and invalid polylines components.

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.

- The call to DXCreate... creates an invalid-component handle that stores the validity state of the data associated with the positions. If there is an initial "invalid positions" component, its contents initialize the handle.

      handle = DXCreateInvalidComponentHandle(field, NULL, "positions")

- Here the call to DXCreate... creates an invalid-component handle associated with `array` (in this case a connections component). No initialization takes place; the handle is initialized to "all valid."

         array = (Array)DXGetComponentValue(field, NULL, "connections");
         handle = DXCreateInvalidComponentHandle(array, NULL, NULL);

  Note that in this example DXCreate... has no way of determining the component name of `array` and, when the handle is converted to an Array, cannot attach a "dep" or "ref" attribute. It is therefore the caller's responsibility to attach the appropriate attribute before placing the Array in a Field. You can determine whether a "dep" or "ref" attribute is needed by examining the type of the invalid Array: `TYPE_INT` or `TYPE_UINT` implies references. As noted earlier, if this component is added to a Field, any previous component of the same name must be explicitly deleted.

  Since it is easier to create an invalid-component handle from a Field and component name (as in the first example), `DXSaveInvalidComponent()` can be used to add the modified validity information to the Field.

- Here the call to DXCreate... creates an invalid-component handle associated with the positions component and initializes it with the invalid-positions Array.

         array = (Array)DXGetComponentValue(field, "positions");
         iarray = (Array)DXGetComponentValue(field, "invalid positions");
         handle = DXCreateInvalidComponentHandle(array, iarray, NULL);

  This example is similar in concept to the first except that it prevents the user from calling `DXSaveInvalidComponent()`.

- This example performs part of the Include operation: it invalidates all connections that reference an invalid position. Any invalid connections remain.

         inv_pos_h = DXCreateInvalidComponentHandle(field, NULL, "positions");
         inv_con_h = DXCreateInvalidComponentHandle(field, NULL, "connections");
         if (!inv_pos_h || !inv_con_h)
            goto error;

         for (i = 0; i < nConnections; i++)
         {
            elt = (int *) DXCalculateArrayEntry(array_handle, i, scratch);
            for (j=0; j < vertsPerElement; j++)
               if (DXIsElementInvalid(inv_pos_h, elt[j]))
               {
                   DXSetElementInvalid(inv_con_h, i);
                   break;
               }
         }
         if (!DXSaveInvalidComponent(field, inv_con_h))
            goto error:

- The following example initially invalidates all connections, and then, for each point, validates the connection that contains it. "IndexOfElementContainingPoint" is a user-supplied routine.

         inv_con_h = DXCreateInvalidComponentHandle(field, NULL, "connections");
         if (!inv_con_h)
            goto error;
         DXSetAllInvalid(inv_con_h);
         for (i=0; i < nPoints; i++)
         {
            j =  IndexOfElementContainingPoint (field, point[i]);
            DXSetElementInvalid(inv_con_h, j);
                   break;
         }
         if (!DXSaveInvalidComponent(field, inv_con_h))
            goto error:

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