IBM Visualization Data Explorer Programmer's Reference

12.3 Array Class

Array Objects store user data, positions, connections, and photometric information (e.g., color or opacity).

Arrays may use explicit lists or one of several compact-coding schemes to store information. This section first describes the generic operations that are applicable to all Arrays, then operations specific to irregular Arrays, and finally operations specific to compact Arrays (i.e., regular, path, product, mesh, constant). For more information about Arrays, see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

Generic Operations

Each Array a contains some number of items n (numbered 0 to n-1). Each item consists of a fixed number of elements of one type, specified when the array is created (see reference #11 for the constants used to specify types).

Note: The routines listed in this subsection apply to both compact and irregular Arrays.

Class DXGetArrayClass()
Returns the subclass of an Array Object. See DXGetArrayClass.
Array DXGetArrayInfo()
Returns the number of items, type, category, rank, and shape of an Array. See DXGetArrayInfo. (For information on rank and shape, see "Arrays" in IBM Visualization Data Explorer User's Guide.)
Array DXTypeCheck() Array DXTypeCheckV();
Check that an Array matches a set of specifications. See DXTypeCheck, DXTypeCheckV.
Pointer DXGetArrayData() (Ref #6.)
Returns a pointer to the start of a global memory area containing the items constituting the data stored in an Array. See DXGetArrayData.
Note: To reduce memory requirements, it is preferable, where possible, to recognize compact arrays with DXGetArrayClass(), and not to expand them by calling DXGetArrayData(). An alternative is the set of Array-handling routines described in "Array Handling".

int DXGetItemSize()
Returns the size in bytes of each individual item of an Array. See DXGetItemSize.
Pointer DXGetArrayDataLocal()
Returns a pointer to the start of memory of a local copy of the data stored in an Array. See DXGetArrayDataLocal.
Array DXFreeArrayDataLocal()
Frees space allocated by DXGetArrayDataLocal(). See DXFreeArrayDataLocal.

Irregular Arrays

Irregular Arrays are used for data that exhibit no particular regularity. They may also be used to manage dynamically growing collections of data whose size is not known in advance. DXNewArray() creates an irregular Array with no items; DXAddArrayData() adds data to an irregular Array; and DXGetArrayData() returns a pointer to an irregular Array.

Note: The routines listed in this subsection apply only to irregular arrays.

Array DXNewArray() Array DXNewArrayV();
Create an irregular Array Object. See DXNewArray, DXNewArrayV.
Array DXAddArrayData()
Adds items to an Array. See Note on Use. See DXAddArrayData.
Array DXAllocateArray()
Allocates space for the data items of an Array. Although this routine is not required, its use will make for more efficient management of memory. See DXAllocateArray.
Array DXTrim()
Frees space previously allocated to an Array but not needed for the number of items in that Array. See DXTrim.

Array DXTrimItems() Removes items from an Array and free the space previously allocated.

Note on Use
There are four ways to add data to irregular arrays.

Add the items one at a time: DXAddArrayData(a, i, 1, item);
Add the items in batches: DXAddArrayData(a, i, n, items);
Add the items all at once: DXAddArrayData(a, 0, n, items);
Allocate the memory as follows:

call DXAddArrayData(a, 0, n, NULL)
get a pointer to the memory:
ptr = DXGetArrayData(a)
put the items directly into global memory "by hand": set the contents (pointed to by the pointer obtained in the preceding step) to the data value.
ptr[i] = itemvalue;
In the examples shown here:

a is the array.
i is the position at which to add an item.
n is the number of items to be added.
item(s) is the address of the item(s) to be added.

Note on Use
There are four ways to add data to irregular arrays. Add the items one at a time: `DXAddArrayData(a, i, 1, item);` Add the items in batches: `DXAddArrayData(a, i, n, items);` Add the items all at once: `DXAddArrayData(a, 0, n, items);` Allocate the memory as follows: call `DXAddArrayData(a, 0, n, NULL)` get a pointer to the memory: `ptr = DXGetArrayData(a)` put the items directly into global memory "by hand": set the contents (pointed to by the pointer obtained in the preceding step) to the data value. ptr[i] = itemvalue; In the examples shown here: `a` is the array. `i` is the position at which to add an item. `n` is the number of items to be added. `item(s)` is the address of the item(s) to be added.

String List Routines

String lists are implemented as arrays of type TYPE_STRING, rank 1, and shape max_string_length+1. Each item should be a NULL-terminated character string.

Array DXMakeStringList() Array DXMakeStringListV();
Create a String list from a given list of strings. See DXMakeStringList, DXMakeStringListV.

Array Handling

Modules may have to handle a variety of different types of Arrays, such as constant, compact (e.g., regular or product), and irregular. DXGetArrayData() can be used on any of these types. However, if the original Array was compact, memory use is increased, sometimes dramatically.

The Array-handling routines simplify the task of dealing with the different types of Arrays at a cost in efficiency. Because it operates on a case-by-case basis, incremental methods available to DXGetArrayData() cannot be used. In addition, each element must be recomputed for each reference to that element. Therefore, multiple references to the same element will pay a penalty in execution time. However, if the array is irregular or constant, this interface can be substituted for the standard DXGetArrayData() with little degradation of performance.

The basic approach is to use DXCreateArrayHandle() for a given array, and then to retrieve the values of elements in that array, using either DXIterateArray(), DXGetArrayEntry(), or DXGetArrayEntries().

DXCreateArrayHandle()
Creates a "handle" to allow convenient access to the items in any Array class. See DXCreateArrayHandle.
Error DXFreeArrayHandle()
Frees the memory allocated for an Array handle. See DXFreeArrayHandle.
Pointer DXGetArrayEntry()
Returns a specified item from an Array. See DXGetArrayEntry, DXGetArrayEntries.
void DXGetArrayEntries()
Returns specified items from an Array. See DXGetArrayEntry, DXGetArrayEntries.
Pointer DXIterateArray()
Iterates through an Array. See DXIterateArray.

Creating Positions and Connections Grids

Compact Arrays allow compact encoding of positions and connections. Four subclasses of Arrays represent 1- and multidimensional regular positions and connections:

positions connections
One-dimensional RegularArray PathArray
n-dimensional ProductArray MeshArray

	positions	connections
One-dimensional	RegularArray	PathArray
n-dimensional	ProductArray	MeshArray

In addition, the subclass Constant Array allows compact encoding of a constant value of any type, category, rank, or shape.

For more information about compact Array Objects, see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.
Note on Use

The generic routine DXGetArrayData() expands the data of a compact Array into an explicitly indexed array and is the preferred means for this purpose. However, it is better still to code your algorithm so that no expansion of the Array is performed.

Note on Use
The generic routine `DXGetArrayData()` expands the data of a compact Array into an explicitly indexed array and is the preferred means for this purpose. However, it is better still to code your algorithm so that no expansion of the Array is performed.

In addition to the low-level routines for creating various compact Arrays (described later), Data Explorer provides the following higher-level routines for creating a regular grid of positions or connections. These routines are to be preferred when there is a choice, because most Data Explorer functions support regular grids of positions or connections efficiently.

Array DXMakeGridPositions() Array DXMakeGridPositionsV();
Create an n-dimensional grid of regularly spaced positions. See DXMakeGridPositions, DXMakeGridPositionsV.
Array DXQueryGridPositions()
Returns information about a regular positions grid. See DXQueryGridPositions.
Array DXMakeGridConnections() Array DXMakeGridConnectionsV();
Construct a grid of regular connections. See DXMakeGridConnections, DXMakeGridConnectionsV.
Array DXQueryGridConnections()
Returns information about a regular connections grid. See DXQueryGridConnections.

Regular Arrays

Regular Arrays encode linear regularity. A regular array is a set of n points lying on a line with a constant spacing between them, representing 1-dimensional regular positions. (The points themselves may be in a higher-dimensional space, but they must lie on a line.) All regular Arrays must be category real (as opposed to complex) and rank 1; the shape is then the dimensionality of the space in which the points are imbedded. (For information on rank and shape, see Chapter 3. "Understanding the Data Model" in IBM Visualization Data Explorer User's Guide.

`RegularArray DXNewRegularArray()`	Creates an Array containing evenly spaced data. See DXNewRegularArray.
`RegularArray DXGetRegularArrayInfo()`	Returns the number of items, the origin, and the delta of a regular Array. See DXGetRegularArrayInfo.

Path Arrays

Path arrays encode linear regularity of connections. A path array is a set of n-1 line segments, where the ith line segment joins points i and i+1. All path arrays have type integer, category real, rank 1, and shape 2.

`PathArray DXNewPathArray()`	Creates an Array describing the connections between a set of points. See DXNewPathArray.
`PathArray DXGetPathArrayInfo()`	Returns the number of points referred to in a path Array. See DXGetPathArrayInfo.

Less Commonly Used Routines

PathArray DXSetPathOffset() PathArray DXGetPathOffset();
Set and retrieve the offset value for the direction of the grid represented by this path. In the case where a path Array is used to define a regular grid of connections that is a part of a partitioned Field, it is useful to know the offset of the partition within the original Field. See DXSetPathOffset and DXGetPathOffset.

Product Arrays

A product Array encodes higher-dimension Arrays as a Cartesian product of lower-dimension Arrays. The resulting set of positions constitutes an n-dimensional "grid" (i.e., a Cartesian product) derived from combining n Arrays.

Since each term is either regular or explicitly indexed, the resulting multidimensional positions are either completely or partially regular.

ProductArray DXNewProductArray() ProductArray DXNewProductArrayV();
Create an Array that is the Cartesian product of a set of regular or irregular position Arrays. See DXNewProductArray, DXNewProductArrayV.
ProductArray DXGetProductArrayInfo()
Returns the number of terms and the terms of a product Array. See DXGetProductArrayInfo.

Mesh Arrays

Mesh Arrays encode multidimensional regularity of connections. A mesh Array is a product of a set of connections Arrays. The product is a set of interpolation elements where the product has one interpolation element for each pair of interpolation elements in the two multiplicands, and the number of sample points in each interpolation element is the product of the number of sample points in each of the multiplicands' interpolation elements. This represents multidimensional regular connections. Each term may be either regular or not, resulting in either completely regular (for example, cubes) or partially regular (for example, prisms) multidimensional connections.

MeshArray DXNewMeshArray() MeshArray DXNewMeshArrayV();
Create an Array that is the product of a set of regular or irregular connection Arrays. See DXNewMeshArray, DXNewMeshArrayV.
MeshArray DXGetMeshArrayInfo()
Returns the number of terms and the terms of a mesh Array. See DXGetMeshArrayInfo.

Less Commonly Used Routines

MeshArray DXSetMeshOffsets() MeshArray DXGetMeshOffsets();
Set and retrieve the offset values along each dimension of a mesh. When a Mesh Array is used to define a regular grid of connections that is a part of a partitioned Field, it is useful to know the offset of the partition within the original Field. See DXSetMeshOffsets and DXGetMeshOffsets.

Constant Arrays

Constant Arrays define Arrays that contain a number of items with the same value. These items may be of any type, category, rank, and shape.

ConstantArray DXNewConstantArray() ConstantArray DXNewConstantArrayV();
Create an Array containing constant data. See DXNewConstantArray, DXNewConstantArrayV.
Array DXQueryConstantArray()
Determines if an Array contains constant data and, if so, returns number of items and data value. See DXQueryConstantArray.
Pointer DXGetConstantArrayData()
Returns a pointer to the value stored in a Constant Array. See DXGetConstantArrayData.

[Data Explorer Home Page]

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

`Array DXNewArray() Array DXNewArrayV();`	Create an irregular Array Object. See DXNewArray, DXNewArrayV.
`Array DXAddArrayData()`	Adds items to an Array. See Note on Use. See DXAddArrayData.
`Array DXAllocateArray()`	Allocates space for the data items of an Array. Although this routine is not required, its use will make for more efficient management of memory. See DXAllocateArray.
`Array DXTrim()`	Frees space previously allocated to an Array but not needed for the number of items in that Array. See DXTrim.
`Array DXTrimItems()`	Removes items from an Array and free the space previously allocated.

`DXCreateArrayHandle()`	Creates a "handle" to allow convenient access to the items in any Array class. See DXCreateArrayHandle.
`Error DXFreeArrayHandle()`	Frees the memory allocated for an Array handle. See DXFreeArrayHandle.
`Pointer DXGetArrayEntry()`	Returns a specified item from an Array. See DXGetArrayEntry, DXGetArrayEntries.
`void DXGetArrayEntries()`	Returns specified items from an Array. See DXGetArrayEntry, DXGetArrayEntries.
`Pointer DXIterateArray()`	Iterates through an Array. See DXIterateArray.

`Array DXMakeGridPositions() Array DXMakeGridPositionsV();`	Create an n-dimensional grid of regularly spaced positions. See DXMakeGridPositions, DXMakeGridPositionsV.
`Array DXQueryGridPositions()`	Returns information about a regular positions grid. See DXQueryGridPositions.
`Array DXMakeGridConnections() Array DXMakeGridConnectionsV();`	Construct a grid of regular connections. See DXMakeGridConnections, DXMakeGridConnectionsV.
`Array DXQueryGridConnections()`	Returns information about a regular connections grid. See DXQueryGridConnections.

`ProductArray DXNewProductArray() ProductArray DXNewProductArrayV();`	Create an Array that is the Cartesian product of a set of regular or irregular position Arrays. See DXNewProductArray, DXNewProductArrayV.
`ProductArray DXGetProductArrayInfo()`	Returns the number of terms and the terms of a product Array. See DXGetProductArrayInfo.

`MeshArray DXNewMeshArray() MeshArray DXNewMeshArrayV();`	Create an Array that is the product of a set of regular or irregular connection Arrays. See DXNewMeshArray, DXNewMeshArrayV.
`MeshArray DXGetMeshArrayInfo()`	Returns the number of terms and the terms of a mesh Array. See DXGetMeshArrayInfo.

`ConstantArray DXNewConstantArray() ConstantArray DXNewConstantArrayV();`	Create an Array containing constant data. See DXNewConstantArray, DXNewConstantArrayV.
`Array DXQueryConstantArray()`	Determines if an Array contains constant data and, if so, returns number of items and data value. See DXQueryConstantArray.
`Pointer DXGetConstantArrayData()`	Returns a pointer to the value stored in a Constant Array. See DXGetConstantArrayData.