# IBM Visualization Data Explorer Programmer's Reference

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

## 13.4 Object Class

The next four subsections summarize the type definitions and routines that apply to the Object class.

### Type Definitions

An Object is represented by a pointer to a C structure stored in global memory. The content of the structure is private to the implementation. A `typedef` is provided for each class of Object:

    typedef struct object *Object;
    typedef struct string *String;
    typedef struct private *Private;
    typedef struct field *Field;

    typedef struct group *Group;
    typedef struct multigrid *Multigrid
    typedef struct series *Series;
    typedef struct compositefield *CompositeField;

    typedef struct array *Array;
    typedef struct regulararray *RegularArray;
    typedef struct patharray *PathArray;
    typedef struct productarray *ProductArray;
    typedef struct mesharray *MeshArray;

    typedef struct interpolator *Interpolator;

    typedef struct xform *Xform;
    typedef struct screen *Screen;
    typedef struct clipped *Clipped;
    typedef struct camera *Camera;
    typedef struct light *Light;

An `enum` provides a number for each class and subclass:

    typedef enum {
        CLASS_MIN,
        CLASS_OBJECT,
        CLASS_PRIVATE,
        CLASS_STRING,
        CLASS_FIELD,

        CLASS_GROUP,
        CLASS_MULTIGRID,
        CLASS_SERIES,
        CLASS_COMPOSITEFIELD,

        CLASS_ARRAY,
        CLASS_REGULARARRAY,
        CLASS_PATHARRAY,
        CLASS_PRODUCTARRAY,
        CLASS_MESHARRAY,

        CLASS_INTERPOLATOR,
        CLASS_FIELDINTERPOLATOR,
        CLASS_GROUPINTERPOLATOR,
        CLASS_LINESRR1DINTERPOLATOR,
        CLASS_LINESRI1DINTERPOLATOR,
        CLASS_QUADSRR2DINTERPOLATOR,
        CLASS_QUADSII2DINTERPOLATOR,
        CLASS_TRISRI2DINTERPOLATOR,
        CLASS_CUBESRRINTERPOLATOR,
        CLASS_CUBESIIINTERPOLATOR,
        CLASS_TETRASINTERPOLATOR,

        CLASS_GROUPITERATOR,
        CLASS_ITEMITERATOR,

        CLASS_XFORM,
        CLASS_SCREEN,
        CLASS_CLIPPED,
        CLASS_CAMERA,
        CLASS_LIGHT,
        CLASS_MAX,
        CLASS_DELETED
    } Class;

### Classes and Subclasses

Every Data Explorer Object is a member of `CLASS_OBJECT` and thus can be manipulated with generic-Object-class routines like `DXDelete()` and `DXGetObjectClass()`. Each Data Explorer Object is also a member of one of the subclasses of `CLASS_OBJECT` (e.g., `CLASS_FIELD`, `CLASS_GROUP`, and so on). Two of these subclasses (`CLASS_GROUP` and `CLASS_ARRAY`) themselves have subclasses (see Table 1).

For any Object, `DXGetObjectClass()` returns the name of the "lowest" subclass to which that Object belongs. If an operation does not require a particular subclass of Object, it will not be affected if the Object is a not a member. If an operation does require a particular subclass, however, `DXGetGroupClass()` or `DXGetArrayClass()` can be used to identify it.

- For Groups, `DXGetGroupClass()` returns one of its three subclasses or (if the Group is generic) `CLASS_GROUP`.
- For Arrays, `DXGetArrayClass()` returns one of its five subclasses or (if the Array is generic) `CLASS_ARRAY`.

Any member of (superclass) `CLASS_ARRAY` or `CLASS_GROUP` can be manipulated with generic superclass routines such as `DXGetGroupType()` and `DXGetArrayInfo()`.

### Object Routines

A number of routines can operate on any Object.

`Class DXGetObjectClass()` | Returns the class of an Object. See DXGetObjectClass.
`Error DXDelete()` | Deletes a reference to an Object. See DXDelete.
`Object DXSetAttribute() Object DXDeleteAttribute();` | Add or remove a named attribute from an Object. See DXSetAttribute, DXDeleteAttribute.
`Object DXGetAttribute() Object DXGetEnumeratedAttribute();` | Retrieve an attribute from an Object. See DXGetAttribute and DXGetEnumeratedAttribute. The first retrieves a named attribute from an Object; the second, the nth attribute.
`Object DXGetFloatAttribute()` | Retrieves a named attribute from an Object, verifies that its contents are a floating-point number, and returns that number. See DXGetFloatAttribute.
`Object DXGetIntegerAttribute()` | Retrieves a named attribute from an Object, verifies that it contains an integer number, and returns that number. See DXGetIntegerAttribute.
`Object DXGetStringAttribute()` | Retrieves a named attribute from an Object, verifies that it contains a string, and returns a pointer to that string. See DXGetStringAttribute.
`Object DXSetFloatAttribute() Object DXSetIntegerAttribute(); Object DXSetStringAttribute();` | Associate a floating-point, integer, or string attribute with an Object. See DXSetFloatAttribute, DXSetIntegerAttribute, and DXSetStringAttribute.

Objects can also be copied:

    enum copy {
        COPY_ATTRIBUTES,
        COPY_HEADER,
        COPY_STRUCTURE
    };

`Object DXCopy()`

Copies the structure of an object. The `COPY_` parameter determines the depth to which an Object is copied:

- `COPY_ATTRIBUTES` Creates a new Object of the same type as the old and copies all attributes and type information. It does not put references to members, components, etc. into the new object.
- `COPY_HEADER` Copies only the header of the immediate Object. It does not copy the attributes, members, etc.; instead it puts references to them into the new Object.
- `COPY_STRUCTURE` Is the parameter most frequently used with this routine.
  - For Groups: copies the Group header and recursively copies all Group members.
  - For Fields: copies the Field header. It does not copy the components (which are usually Arrays); instead it puts references to the components into the resulting Field.
  - For Arrays: passes back a pointer to the Array and makes no copy.

On error, the routine returns `NULL` and sets an error code. See DXCopy. See also Chapter 6. "Working with Positions", Chapter 7. "Working with Connections", and Chapter 8. "Importing Data" for examples of this routine's use.

Less Commonly Used Routines

`Object DXReference()` | Increments the reference count of a specified Object. See DXReference.
`Error DXUnreference()` | Removes a reference from an Object without deleting it. See DXUnreference.
`int DXGetObjectTag() Object DXSetObjectTag();` | Manipulate unique Object identifiers. See DXGetObjectTag, DXSetObjectTag.
`Object DXCopyAttributes()` | Copies attributes from one Object to another. See DXCopyAttributes.

### Setting Data Types

The data type of Arrays, Fields, and Groups are determined as follows.

- `Arrays`: The data type is set when the Array is created. (See 12.3 , "Array Class".)
- `Fields`: The data type is that of the "data" component, if there is one.
- `Groups`: The data type is set explicitly by `DXSetGroupType()`; it is set implicitly for Series and Composite Groups (because members of these Groups must be of the same type).

(Ref #11.)

    typedef enum {
        TYPE_BYTE                  (1 byte)
        TYPE_UBYTE                 (2 bytes)
        TYPE_SHORT                 (2 bytes)
        TYPE_USHORT                (2 bytes)
        TYPE_FLOAT                 (4 bytes)
        TYPE_INT                   (4 bytes)
        TYPE_UINT                  (4 bytes)
        TYPE_DOUBLE                (8 bytes)
        TYPE_HYPER                 (8 bytes)
        TYPE_STRING                (dynamic)

    } Type;
    typedef enum {
        CATEGORY_REAL
        CATEGORY_COMPLEX

    } Category;

`Object DXGetType()` | Returns the type, category, rank, and shape of an Object. See DXGetType.
`int DXTypeSize() int DXCategorySize();` | The first returns the size (in bytes) of a variable of a given type; the second, the size multiplier for a given category. See DXTypeSize, DXCategorySize.

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