SclDestroy

Overview

Scl permits various types of objects to be created for different purposes. The objects that are created include:

Swas (Surpac work areas)
Graphics layers
Guido forms
Triobjects, Trisolations and Triangles
Strings, Segments and Triangles
Delete, Insert, InsertUpdate and Update operations on database tables

The SclDestroy command permits each of the objects that are created by various Scl commands to be destroyed. Reasons for wishing to destroy Scl objects are:

You want to free the memory associated with the object so that it can be reused by the application (Surpac) or by some other program.
The object is no longer required, a string in a SWA for example, and it must be destroyed, before saving to a file perhaps.
Database operations MUST be destroyed if they are to be committed to the database table. If, for example, an insert operation is not destroyed, there is no guarantee that the operation will result in permanent changes to the database table.

There are no intrinsic limits to how many objects that might be created using an Scl script. The only effective limits are the amount of physical memory and swap space that is available on the computer on which the Scl script is being run. Scl takes care of allocation and deallocation of the memory required to store and manipulate the various objects that are created by Scl.

The implication is therefore that Scl programmers don't need to concern themselves with memory management to a certain extent. Ultimately, when Surpac exits, all memory associated with objects created using Scl commands is freed for use by the operating system and other applications. When the Tcl interpreter embedded in Surpac finishes executing an Scl script most, but not necessarily all, memory associated with objects created by the Scl commands is freed for reuse by Surpac, the operating system or other applications.

Some objects that Scl commands can create, persist beyond the end of execution of the Scl script. It is these objects that must be given careful consideration to ensure whether or not they should be freed (destroyed) before the script terminates. Remember that the memory is ultimately freed when Surpac exits. It is more important for the development of advanced Scl applications than simple Scl applications.

The objects that can persist after an Scl script terminates, that must be considered to determine whether or not they should be destroyed before the Scl script terminates are:

SWAs (and Graphics Layers)
Strings
Segments
Points
Triobjects
Trisolations
Triangles

Fortunately, because strings, segments, points, triobjects, trisolations and triangles all descend from a SWA, destroying the SWA will ensure that all descendant objects are also destroyed. Scl ensures that this occurs. The only decision that must be made by the Scl programmer with regard to SWAs and whether they should be destroyed using SclDestroy before the Scl script terminates is, "Is this SWA, and by implication all objects within it, required by the user after the script finishes?"

If the answer to this question is "yes", the SWA should not be destroyed before the script terminates. If the answer to this question is "no" then the SWA should be destroyed.

It is possible though to use SclDestroy to destroy selected objects in a SWA if they are no longer required. An example of this is where a specific string, segment, point, triobject or trisolation in a SWA is no longer required. SclDestroy can be used to destroy the object in question.

Other objects that are commonly considered as candidates for destruction during the course of script execution include:

Synopsis

SclDestroy ObjectHandle

Description

Destroy the object, and all its descendant objects, referred to by the ObjectHandle variable. All memory associated with the objects that are destroyed is freed for reuse by Surpac.

Notes:

If you delete all child objects in a parent object, the parent object is destroyed. For example, if you delete all points in a segment, the segment is destroyed. As a result, the object handle of the parent becomes invalid, and if a script attempts to use the parent object handle, a -1 error code is returned.
If the object in question is displayed in a 3D graphics viewport, the object is also erased from the viewport. There is no need to erase the object before destroying the object with the SclErase command.

Arguments

ObjectHandle

Passed by reference. This is the name of the variable to which the handle to the object being destroyed has been assigned.

Examples

#
# This example shows how, after creating 2 segments in a string, the
# second segment can be destroyed. Comparing the 2 result files
# test1.str and test2.str shows how the second segment has been deleted
# from the string in test2.str
#
SclCreateSwa SwaHandle "temporary swa"
$SwaHandle SclCreateString StringHandle 1
$StringHandle SclCreateSegment SegmentHandle 0
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 1.0
$PointHandle SclSetValueByName y 2.0
$PointHandle SclSetValueByName z 3.0
# notice how the segmentHandle variable is re-used to refer to the new segment
$StringHandle SclCreateSegment SegmentHandle [$StringHandle SclCountItems]
$SegmentHandle SclCreatePoint PointHandle 0
$PointHandle SclSetValueByName x 4.0
$PointHandle SclSetValueByName y 5.0
$PointHandle SclSetValueByName z 6.0
# save a string file with both segments
$SwaHandle SclSwaSaveStringFile test1.str
# delete the second segment
SclDestroy SegmentHandle
$SwaHandle SclSwaSaveStringFile test2.str
# delete the swa and all data contained in it
SclDestroy SwaHandle