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, with the element pointer and all subsequent following elements moving forward one position.  This results in the element pointer’s pointing after the object just inserted.  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()));
 

This will result in the object variable’s getting the value of the newly created object as well as placing 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 reclamation of storage from obsolete held objects. 

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), DsHoldObj(3D)

September 29, 2021