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

deleteinstance and finally

If deleteinstance ($instancename) is used inside a try block of a try-finally-endtry construct and causes the current instance to get deleted, further code execution stops because the current runtime context has been deleted. The finally block is not executed in this case. The cleanup operation is still executed, but should not be used to clean up exception related context.

It is best practice to delete an instance from outside the same instance, to ensure all context stays available while handling any exceptions. If deleting the current instance cannot be avoided, place any module-related cleanup logic just before the deleteinstance<$instancename> or exit statement, and not in the finally block.