# IBM Visualization Data Explorer Programmer's Reference

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

### DXAddArrayData

Function Adds items to an Array.

Syntax

    #include <dx/dx.h>
    Array DXAddArrayData(Array a, int start, int n, Pointer data)

.

Functional Details Adds `n` items to Array `a`, starting at the numbered item specified by `start`. The additions may replace or supplement items already defined. If `data` is not `NULL`, the routine copies the data into the Array; otherwise, it increases the number of items in the Array by `n`, but leaves them uninitialized.

To avoid having memory allocated every time, `DXAddArrayData` may allocate more than is needed for the requested number of items. If Array `a` is part of a Field, any extra space will be freed when `DXEndField` is called. If it is not part of a Field, `DXTrim` can be called to free the extra space, though this is not required.

To allocate space "up front" for an Array of known size, use `DXAddArrayData(a, 0, n, NULL)`, which is the preferred means for preallocating space for the data.

`DXAllocateArray(a, 0, n, NULL)` also preallocates space, but the number of items in the Array will be 0. If `DXAllocateArray` is called, `DXTrim` can be called to resize the Array to the space required for the actual number of items.

Allocating more space for an Array may result in its being copied to a new location in memory. If you call `DXGetArrayData` to obtain a pointer for an Array and then allocate more space for it, you must call `DXGetArrayData` again because the pointer may no longer be valid.

There are four ways to add data to irregular Arrays:

- Add items one at a time: `DXAddArrayData(a, i, 1,item)`.
- Add items in batches: `DXAddArrayData(a, i, n, items)`.
- Add multiple items all at one time: `DXAddArrayData(a, 0, n, items)`.
- Allocate the memory: call `DXAddArrayData(a, 0, n, NULL)`; get a pointer to global memory with `DXGetArrayData(a)`; and put the items directly into global memory "by hand."

Return Value Returns `a` or returns `NULL` and sets an error code.

See Also `DXAllocateArray, DXEndField, DXGetArrayData, DXTrim,` "Irregular Arrays".

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