# IBM Visualization Data Explorer Programmer's Reference

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

# Chapter 12. Working with Data Model Objects

Partial Table-of-Contents

- 12.1 Field Class
- 12.2 Group Class
- Generic Operations
- Series Groups
- MultiGrid Groups
- Composite Fields
- Parts
- 12.3 Array Class
- Generic Operations
- Irregular Arrays
- String List Routines
- Array Handling
- Creating Positions and Connections Grids
- Regular Arrays
- Path Arrays
- Product Arrays
- Mesh Arrays
- Constant Arrays
- 12.4 String Class
- 12.5 Private Class
- 12.6 Printing Objects
- 12.7 Field Construction
- Points and Dependent Data
- Connections
- Standard Components
- 12.8 Extracting Module Parameters
- 12.9 Creating Simple Data Explorer Objects
- 12.10 Component Manipulation
- 12.11 Data Import and Export
- Data Explorer Format Files
- netCDF Data

  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.

  [ 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 | Contact Data Explorer | Same document on Data Explorer Home Page ]

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