IBM Visualization Data Explorer Programmer's Reference

DXCopy

Function

Performs various copying operations.

Syntax

#include <dx/dx.h>

Object DXCopy(Object o, enum copy copy)

Functional Details

The DXCopy operations differ in the depth to which they copy the structure of an Object o. Depth is specified by the copy parameter, which may be one of the following:

• COPY_STRUCTURE:
  • For Groups, copies the Group header and recursively copies all Group members.
  • For Fields, copies the Field header but does not copy the components (which are generally Arrays); instead it puts references to the components of the given Object into the resulting Field.
  • For Arrays, passes back a pointer to the data and makes no copy.

• COPY_HEADER: Copies only the header of the immediate Object but does not copy attributes, members, components, and so on; instead it puts references to them into the new Object.

  The Object created can be deleted with DXDelete. See 4.2 , "Memory Management".

• COPY_ATTRIBUTES: Creates a new Object of the same type as the old, and copies all attributes and type information, but does not put references (to members, components, and so on) in the new Object.

Notes:

1. Because of the data-flow execution model used by Data Explorer, it is critical that no module actually alter its inputs. Instead, DXCopy is generally used to create a modifiable copy of the input that is then altered and produced as output. This is most often done by using the COPY_STRUCTURE form. This produces a copy of the structure of the input, but uses references to the Arrays of the input, rather than actual copies. Once a structure has been copied in this manner, the Arrays (which are most often found as components of Fields) may be replaced in the copied Field by new results. The result will be a copy of the input that shares all unchanged data with the original, thereby saving memory space.

2. DXCopy applied to an Object of type Array performs no copy and simply returns its input. This presents the problem that in order to clean up, copied Objects of other types may be deleted without deleting the original, while the result of applying DXCopy to Arrays may not be deleted without deleting the original.

Return Value

Returns the copy or returns NULL and sets an error code.

See Also

DXCopyAttributes, DXNewField, DXNewGroup

"Object Routines".

[Data Explorer Home Page]