IBM Visualization Data Explorer Programmer's Reference

Chapter 12. Working with Data Model Objects

Partial Table-of-Contents

This chapter describes the programming interface for creating and manipulating the basic Objects of the Data Explorer data model (some Objects are discussed in later chapters). For a brief summary of the data model, see Chapter 1. "Overview". For a detailed description, see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

Data Explorer is an object-oriented graphical application. Its objects are data structures in global memory, they are passed by reference, and their contents are private to the implementation. See Table 1.

Table 1. Data Explorer Objects

The first column shows the hierarchical relationship of the Objects to one another. For subclasses  Field  through  Private , see 12.1 , "Field Class" through 12.5 , "Private Class" in this chapter; for  Interpolator , see Chapter 14. "Data Processing"; and for the remainder, see Chapter 16. "Rendering".
Type	Description	Class
Object	Object Class	CLASS_OBJECT
Field	Data sampled on a regular or irregular grid	CLASS_FIELD
Group	Collections of Objects	CLASS_GROUP
Series	Time (or other) series	CLASS_SERIES
Multigrid	Group of Fields to be treated as one Field	CLASS_MULTIGRID
Composite Field	Group of Fields to be treated as one Field	CLASS_COMPOSITEFIELD
Array	Dynamic Arrays of data such as points	CLASS_ARRAY
Regular Array	One-dimensional series of evenly spaced points	CLASS_REGULARARRAY
Path Array	One-dimensional series of connected line segments	CLASS_PATHARRAY
Product Array	Regular or semi-regular grid positions	CLASS_PRODUCTARRAY
Mesh Array	Regular or semi-regular grid connections	CLASS_MESHARRAY
Constant Array	Array with a constant value	CLASS_CONSTANTARRAY
String	Object containing a string	CLASS_STRING
Private	Object pointing to private user data	CLASS_PRIVATE
Interpolator	Used to query Fields for data values	CLASS_INTERPOLATOR
Xform	Transformation matrix applied to an Object	CLASS_FORM
Screen	Object aligned to the screen	CLASS_SCREEN
Clipped	One Object clipped by another	CLASS_CLIPPED
Camera	Viewpoint, viewport, resolution	CLASS_CAMERA
Light	Lights	CLASS_LIGHT
Note: Any Group other than the three types listed here is a generic Group. Any Array other than the five types listed here is an irregular Array.

12.1 Field Class

Each Field has some number of named components. Each component has a value (usually an Array) and some number of attributes, whose values are often strings or numbers. However, in the data model both components and attributes can be any Object. The defined components and attributes are listed in Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

Field DXNewField()	Creates a new Field Object. See Note on Use, and DXNewField.
Field DXSetComponentValue()	Adds a component to a Field. See Note on Use, and DXSetComponentValue.
Field DXSetComponentAttribute()	Adds or removes a named attribute from a component of a Field. See DXSetComponentAttribute.
Object DXGetComponentValue()	Returns a specified component of a Field. See Note on Use See DXGetComponentValue.

Note on Use
The following code segment illustrates how to make a component of one Field also a component of another Field: f = DXNewField(); if (!f) return ERROR; c = DXGetComponentValue(oldfield, "positions"); if (!DXSetComponentValue(f, "positions", c)) return ERROR;

Object DXGetComponentAttribute()	Returns a named attribute of a specified component of a Field. See DXGetComponentAttribute.
Object DXGetEnumeratedComponentValue() Object DXGetEnumeratedComponentAttribute()	Return a component or component attribute by index. These routines can be used to retrieve the components or component attributes when their names are not known. See DXGetEnumeratedComponentValue and DXGetEnumeratedComponentAttribute.
Field DXDeleteComponent()	Deletes a named component from a Field. See DXDeleteComponent.

Less Commonly Used Routines

Error DXComponentReq() Error DXComponentOpt(); Error DXComponentReqLoc(); Error DXComponentOptLoc();

Access or type-check a component in a Field. See Note on Use. See also DXComponentReq, DXComponentOpt, DXComponentReqLoc, DXComponentOptLoc.

Note on Use

An example of the expected use of DXComponentReq() follows: a = DXGetComponentValue(f, "positions"); if (!DXComponentReq(a, &points, &npoints, 0, TYPE_FLOAT, 3)) return NULL; a = DXGetComponentValue(f, "colors"); if (!DXComponentOpt(a, &colors, NULL, npoints, TYPE_FLOAT, 3)) return NULL; if (colors) ... The first two statements check and retrieve a required "positions" component, while the next two check and retrieve an optional "colors" component that must have the same number of elements. Since the second call uses DXComponentOpt(), the program must check colors for NULL to determine whether the colors were present.

[Data Explorer Home Page]