NAME

DgReplaceObj − Replace an object in the currently open group

SYNOPSIS

C:

void DgReplaceObj(object)
DtObject object;

FORTRAN:

CALL DGRO(OBJECT)
INTEGER∗4 OBJECT

DESCRIPTION

DgReplaceObj places the object, object, in the currently open group.  If the group’s element pointer is not at the end of the group, the object replaces the object immediately following the group’s element pointer.  If the group’s element pointer is after the last element in the group, the object is appended to the end of the group.  In both cases, the group element pointer remains pointing at the object just replaced or inserted; i.e., the element pointer never moves. 

The most common way to call the DgReplaceObj function is:

 DgReplaceObj(DoXXXX());
 

where the DoXXXX() call creates and returns an object of type XXXX, and this object is added to the currently open group through the DgReplaceObj call.  One can also create an object through a separate call to a DoXXXX routine and then call the DgReplaceObj routine with the object directly:

 object = DoXXXX();
DsHoldObj(object);
DgReplaceObj(object);
 

One may also call this function in the following manner:

 DgReplaceObj(DsHoldObj(object=DoXXXX()));
 

This will place the handle of the newly created object in object and place the object in the currently open group. 

The call to DsHoldObj <DSHO> is needed only if the user also wants to use the object created for other purposes.  Note that any object held with a DsHoldObj <DSHO> will not be deleted.  The application program is always responsible for reclaiming storage from held objects that are no longer needed. 

ERRORS

DgReplaceObj will fail if passed an invalid object. 

[WARNING - invalid or deleted object]

DgReplaceObj will fail if no group is currently open. 

[WARNING - a group is not currently open]

SEE ALSO

DgAddObjToGroup(3D), DgInqOpen(3D), DgOpen(3D), DoGroup(3D), DoInLineGroup(3D), DsHoldObj(3D)

September 02, 1992