NAME

DgAddObj − Add an object to the currently open group

SYNOPSIS

C:

void DgAddObj(object)
DtObject object;

FORTRAN:

CALL DGAO(OBJECT)
INTEGER∗4 OBJECT

DESCRIPTION

DgAddObj adds an object, object, to the currently open group. The object is inserted into the group at the position indicated by the element pointer, and the element pointer is moved so that it points to the position directly below the new object.  If another element was in the insertion position, the element and all elements below it are moved forward one position.  DgReplaceObj <DGRO> is used to replace the object specified by the group’s element pointer. 

The most common way to call the DgAddObj function is:

 DgAddObj(DoXXXX());
 

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

 object = DoXXXX();
DsHoldObj(object);
DgAddObj(object);
 

One may also call this function in the following manner:

 DgAddObj(DsHoldObj(object=DoXXXX()));
 

Here, the object variable gets the value of the newly created object and is placed in the currently open group as well. 

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 become obsolete. 

ERRORS

DgAddObj will fail if object is not a valid object. 

[WARNING - invalid or deleted object]

DgAddObj will fail if no group is currently open. 

[WARNING - a group is not currently open]

SEE ALSO

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

September 02, 1992