NAME

DsHoldObj − Place a hold on an object

SYNOPSIS

C:

DtObject DsHoldObj(object)
DtObject object;

FORTRAN:

INTEGER∗4 DSHO(OBJECT)
INTEGER∗4 OBJECT

DESCRIPTION

DsHoldObj places a hold on an object specified by the parameter object, and it returns the object handle. 

There are two ways objects keep track of how they are being used.  First, every object maintains a reference count that indicates how many times it is referenced by other objects.  Second, the object maintains a  hold flag that indicates whether the user has any references to it.  The user has explicit control over this flag.  If an object’s reference count is 0, and its hold flag is DcFalse <DCFALS>, then it is considered deletable: the object is removed from the database, its storage area is destroyed, and its object handle is no longer valid. 

When an object is created, its reference count is 0, and its hold flag is  DcFalse <DCFALS>.  If the user adds the object to a group, its reference count is automatically incremented, and it is not considered deletable by the database.  If the user wishes to reference an object’s handle outside of the current database and it is not referenced within the database, the user should call the DsHoldObj function with the object handle.  This causes the object’s hold flag to be set to true.  The corresponding routine DsReleaseObj <DSRO> releases the hold on the object when the user has no further need of it.  The user can determine whether a hold has been placed on the object by calling DsInqHoldObj <DSQHO>. 

A common way to call the DsHoldObj function is:

 object = DsHoldObj(DoXXXX());

where the DoXXXX() call creates and returns an object of type XXXX.  A hold is placed on the object through the DsHoldObj call.  One can also create an object through a separate call to a DoXXXX routine and then call the DsHoldObj routine with the object directly:

 object = DoXXXX();
DsHoldObj(object);

The user may also call this function in the following manner:

DsHoldObj(object=DoXXXX());

This will result in creating the object, setting the object variable to its handle, and placing a hold on the object. 

ERRORS

DsHoldObj will fail if passed an invalid object. 

[WARNING - invalid or deleted object]

SEE ALSO

DsInqHoldObj(3D), DsReleaseObj(3D)

September 02, 1992