Object Utility Routines - Object Utility Routines The following routines provide various utility calls deal ObjectTools global basis OT OT rarr Longint Parameter Type Description Function result Longint larr application compiled interpreted Description nbspOT same command Compiled application but works correctly version standalone v606 unlike Compiled application command OT OT Parameter Type outHandles Longint array larr Receives list all current objects Discussion time object created whether through OT New OT Copy OT GetObject OT BLOBToObject ObjectTools adds new object handle to an internal list When object cleared OT Clear objectrsquos handle is removed from listOT GetHandleList retrieves internal list array mainly use in debugging Normally would have need use methodSee OT New OT Clear OT modi64257ed version OT GetOptions rarr Longint Parameter Type Function result Longint larr A set bit Discussion GetOptions returns 32bit number contains bits representing different options ObjectTools use bit test operator test state given option bit set bit clear operators set clear individual options Currently two options de64257ned ObjectTools provides named constants testing options Option Bit Default OT off OT ExactTagMatch off OT on OT VariantItems off OT default item cannot found OT routines return default value OT option set default value still returned but ObjectTools generate error set OK zero OT ExactTagMatch new version By default tag names matched regard case but diacritical marks are OT ExactTagMatch option set tag names matched exactly using both case diacritical marks Example To turn exact tag matching would use following code GetOptions ExactTagMatch OT SetOptions options OT new version Previous ObjectTools add embedded objects another object had create embedded object put clear it was tedious ultimately unnecessary ObjectTools autocreate embedded objects default whenever put item tag contains embedded item references example NewOT above example after call OT PutString obj contains embedded object contains embedded object contains string This facility make considerably easier create complex object hierarchies than ObjectTools 1x OT VariantItems new version By default try put value item different type error generated rationale behind behavior prevent unintended changing type carelessness negligence However what want change type items such your desire now setting OT VariantItems option example NewOT This generates errorSet allow variant item types try againOT GetOptions This work item now longintSee OT SetOptions OT OT GetVersion rarr String Parameter Type Function result String larr The current version ObjectTools Discussion GetVersion returns textual representation current numeric version ObjectTools along information about platform build type OT modi64257ed version OT Type Description inSerialNum String ObjectTools serial number result Longint Result code larr Description OT Register donothing routine since ObjectTools free remains ObjectTools compatibility legacy code OT modi64257ed version OT Type Description inNewHandler String Name method execute result String name previous errorlarr handler Discussion OT sets action perform when ObjectTools encounters error previous error handler returned By default action taken when error occurs If pass name existing method inHandler method get called when error occurs method take two String parameters parameter contain description error occurred second parameter contain name ObjectTools method was called when error occurred Note If put TRACE statement end your error handler method when error occurs debugger come up step line line after caused error Whether not error handler set whenever error occurs

Object Utility Routines

The following routines provide various utility calls that deal with ObjectTools on a global basis.

OT CompiledApplication → Longint
Parameter	Type		Description
Function result		Longint	← 1 if the application is compiled, 0 if interpreted
Description

OT CompiledApplication is the same as the 4D command Compiled application, but it works correctly with version 4D standalone v6.0.6, unlike the Compiled application command.

OT GetHandleList version 1

OT GetHandleList(outHandles)

Parameter	Type		Description
outHandles	Longint array	←	Receives a list of all current objects
Discussion

Any time an object is created, whether through OT New, OT Copy, OT GetObject, or OT BLOBToObject, ObjectTools adds the new object handle to an internal list. When an object is cleared with OT Clear, the object’s handle is removed from the list.

OT GetHandleList retrieves this internal list into an array. This is mainly of use in debugging. Normally you would have no need to use this method.

OT GetOptions version 1 modiﬁed version 2.0

OT GetOptions → Longint
Parameter	Type		Description
Function result	Longint	←	A set of 32 bit ﬂags
Discussion

OT GetOptions returns a 32-bit number which contains bits representing the different options for ObjectTools. You can use the 4D ?? bit test operator to test the state of a given option and the ?+ (bit set) or ?- (bit clear) operators to set or clear individual options.

Currently, there are two options deﬁned. ObjectTools provides named constants for testing the options.

Option Bit Default

OT FailOnItemNotFound	0	0 (off)
OT ExactTagMatch	1	0 (off)
OT AutoCreateObjects	2	1 (on)
OT VariantItems	3	0 (off)
OT FailOnItemNotFound

By default, if an item cannot be found, the OT Get<type> routines will return a default value. If the OT FailOnItemNotFound option is set, a default value will still be returned but ObjectTools will generate an error and set OK to zero.

OT ExactTagMatch (new in version 1.6)

By default, tag names are matched without regard to case (but diacritical marks are signiﬁcant). If the OT ExactTagMatch option is set, tag names are matched exactly, using both case and diacritical marks.

Example

To turn exact tag matching on, you would use the following code:

C_LONGINT($options)

$options:=OT GetOptions

$options:=$options ?+ OT ExactTagMatch

OT SetOptions ($options)

OT AutoCreateObjects (new in version 2.0)

Previous to ObjectTools 2.0, to add an embedded objects to another object, you had to create the embedded object, put it, then clear it. This was tedious and ultimately unnecessary.

ObjectTools 2.0 will auto-create embedded objects by default whenever you put an item with a tag that contains embedded item references. For example:

C_LONGINT($obj)$obj:=OT NewOT PutString($obj;"one.two.three";"way cool!")

In the above example, after the call to OT PutString $obj contains the embedded object “one”, which contains the embedded object “two”, which contains a string “three”.

This facility will make it considerably easier to create complex object hierarchies than in ObjectTools 1.x.

OT VariantItems (new in version 2.0)

By default, if you try to put a value into an item of a different type, an error is generated. The rationale behind this behavior is to prevent unintended changing of the type by carelessness or negligence.

However, what if you want to change the type of items? If such is your desire, you can now do so by setting the OT VariantItems option. For example:

C_LONGINT($obj)$obj:=OT NewOT PutString($obj;"test";"way cool!")OT PutLong($obj;"test";7) `This generates an error

`Set the ﬂag to allow variant item types and try againOT SetOptions(OT GetOptions | OT VariantItems)OT PutLong($obj;"test";7) `This will work, the item is now a longint

OT Register version 1 modiﬁed version 1.65

OT Register(inSerialNum) Longint

→

Parameter Type Description

inSerialNum String ObjectTools serial number

→

Function result Longint Result code

←

Description

OT Register is a do-nothing routine since ObjectTools is free. It remains in ObjectTools for compatibility with legacy code.

OT SetErrorHandler version 1 modiﬁed version 2.0

OT SetErrorHandler(inNewHandler) String

→

Parameter Type Description

inNewHandler String Name of a 4D method to execute

→

Function result String The name of the previous error

← handler

Discussion

OT SetErrorHandler sets the action to perform when ObjectTools encounters an error. The previous error handler is returned.

By default, action is taken when an error occurs.

If you pass the name of an existing 4D method in inHandler, that method will get called when an error occurs. The method must take two String parameters. The ﬁrst parameter will contain a description of the error that occurred. The second parameter will contain the name of the ObjectTools method that was called when the error occurred.

Note If you put a TRACE statement at the end of your error handler method, when an error occurs the 4D debugger will come up. If you then step one line, you will be at the line after the one that caused the error.

Whether or not an error handler is set, whenever an error occurs the OK variable is set to zero.

OT SetErrorHandler returns the old handler so that you may dynamically change the error handling within your code.

OT SetOptions version 1 modiﬁed version 1.6

OT SetOptions(inOptions)

Parameter	Type		Description
inOptions	Longint	→	Set of 32 bit ﬂags
Discussion

OT SetOptions sets all of the ObjectTools options using a 32-bit number, which contains bits representing the different options.

Because all of the options are set at once, this call should be preceded by a call to OT GetOptions, then the 4D bitwise operators should be used to set or clear individual bit ﬂags.

See “OT GetOptions” for a list of the current options.