Creation Destruction Routines - Creation Destruction Routines The following routines used create destroy ObjectTools objects successfully create valid object before using other ObjectTools routine OT Newversion OT New rarr Longint Parameter Type Function result Longint larr A handle new empty object Discussion new empty object returns it new object added internal list objects When object call OT Clear release memory used object Warning Never attempt pass value ObjectTools routine other than returned New See OT IsObject OT Clear OT Clearversion OT ClearioObject Parameter Type ioObject Longint harr A handle object Discussion object should always call OT Clear release memory occupied object create object lose track its handle longer able release its memory known leak considered Bad Thing ObjectTools maintains internal list all objects have been created but not cleared When object disposed OT Clear removed from list current list created objects available OT GetHandleList method You actually release memory used leaked objects OT GetHandleList OT ClearAll However using these means object memory management not recommended It pass variable directly OT Clear as opposed extremely lucky guess number constant variable set zero Note It legal pass null handle Clear Examples The sample code below demonstrates creating two temporary objects pass method leak while second properly disposed OT Clear NewOT PutString NewOT PutString Clear notLeak The memory releasedIf leave method point not able recoverthe value leak its memory leakSee OT New

Creation and Destruction Routines

The following routines can be used to create and destroy ObjectTools objects. You must successfully create a valid object before using any other ObjectTools routine.

OT New version 1

OT New → Longint
Parameter	Type		Description
Function result	Longint	←	A handle to a new, empty object
Discussion

Creates a new, empty object and returns it. The new object is added to internal list of objects. When you are ﬁnished with the object, call OT Clear to release the memory used by the object.

Warning Never attempt to pass any value to an ObjectTools routine other than that returned by OT New.

OT Clear version 1

OT Clear(ioObject)

Parameter	Type		Description
ioObject	Longint	↔	A handle to an object
Discussion

When you are ﬁnished with an object, you should always call OT Clear to release the memory occupied by the object. If you create an object and then lose track of its handle, you will no longer be able to release its memory. This is known as a leak, and it is considered a Bad Thing.

ObjectTools maintains an internal list of all objects that have been created but not cleared. When an object is disposed of with OT Clear, it is removed from the list. The current list of created objects is available with the OT GetHandleList method.

You can actually release the memory used by leaked objects with OT GetHandleList or OT ClearAll. However, using these as a means of object memory management is not recommended.

It you pass a variable directly to OT Clear (as opposed to an extremely lucky guess at a number constant), the variable will be set to zero.

Note It is legal to pass a null handle (0) to OT Clear.

Examples

The sample code is below demonstrates creating two temporary objects to pass to a method. The ﬁrst one will leak, while the second one is properly disposed with OT Clear.

C_LONGINT($leak;$notLeak)$leak:=OT New
OT PutString ($leak;"name";[Contacts]Name)
$notLeak:=OT New
OT PutString ($notLeak;"address";[Contacts]Address)
MyMethod($leak;$notLeak)
OT Clear ($notLeak) `The memory is released

`If we leave this method at this point, we will not be able to recover
`the value of $leak, so its memory will leak.