deleteinstance

Deletes an instance of a component.

deleteinstance  InstanceName

Parameters

Parameters
Parameter Data Type Description
InstanceName String Name of the instance to be removed.

Return Values

Values returned in $status
Value Description
<0 An error occurred. $procerror contains the exact error.
0 The instance was successfully deleted.
Values commonly returned by $procerror following deleteinstance
Value Error constant Meaning
-57 <UACTERR_NO_INSTANCE> The named instance cannot be found in the component pool.
-162 <UACTERR_DELETE_INSTANCE> Deleting the instance has been postponed because the instance is busy.

For example, operation A1 in INSTA activates operation B1 in INSTB. Operation B1, in turn, activates operation A2 in INSTA. Operation A2 performs an exit, but INSTA cannot be deleted until operations B1 and A1 complete.

-163 <UACTERR_DEL_POSTPONED_CHILD> Deleting the instance has been postponed because the instance has at least one busy child instance. The instance will be deleted when it no longer has busy children.

For example, non-modal Form FRMX starts an attached non-modal form FRMY. While the application is idle, the user clicks on FRMY, activating a trigger which sends a message to FRMX. This message results in an exit (on FRMX), but FRMX cannot be deleted until its child instance FRMY is not busy.

-164 UACTERR_DEL_POSTPONED_PROC The instance is in the process of being deleted.

For example, between a deleteinstance or exit and the time the instance is actually deleted, an attempt is made to activate an operation in the instance being deleted.

Use

Allowed in all component types.

Description

The deleteinstance statement removes the instance named InstName, and all child instances, from the component pool.

If a cleanup operation has been defined for any of the instances being removed, that operation is executed before the instance is removed.

Creating and Deleting Instances

In the following example, the apStart trigger starts a sequence of non-modal forms before allowing the user to take control of the application. When control returns to this trigger, the ProcScript removes any detached instances that are still in the component pool. 

trigger apStart

; start the initial forms
newinstance "form10",$1,"MODALITY=NON-MODAL"
newinstance "form20",$2,"MODALITY=NON-MODAL"
newinstance "form40",$3,"MODALITY=NON-MODAL"
; show them
$1->EXEC()
$2->EXEC()
$3->EXEC()
; let the user play
; control returns to me, so clean up any detached instances
getitem $1, $detachedinstances, 1
while ( $status > 0 )
   deleteinstance $1
   getitem $1, $detachedinstances, 1
endwhile
end

Related Topics