VbScriptXtra v1 for Macromedia Director

VbScriptXtra automation object wrapper - automatic type casting

VbScriptXtra performs automatic type casting to correctly transfer data between Lingo and Automation object and vice versa. VbScriptXtra implicitly performs typecasting operations during processing Lingo method arguments, returning values, and property values.
Automation and Visual Basic supports rather large amount of data types. Lingo has its own Director specific data types. So, VbScriptXtra may not find suitable conversion in all cases, although it provides conversion in the most cases. If VbScriptXtra does not know how to convert the value it will report an error.
See Mapping Lingo types to COM Automation types and Mapping COM Automation types to Lingo types topics below for further details.

Mapping Lingo types to COM Automation types

This conversion is taking place when VbScriptXtra wrapper passes any arguments to the wrapped automation object. This includes assigning property values of the wrapped automation object.
The table below describes Lingo types that are recognized by VbScriptXtra wrapper and into which types they are converted.

Lingo type	Lingo Value (if any)	Automation type
Symbol	#Null	NULL
Symbol	#True	Boolean (true)
Symbol	#False	Boolean (false)
Symbol	other symbols	String
Integer		signed integer 4 bytes
Float		Float 8 bytes
String		String
Date		Float
List of floats		SafeArray (Vector) of Doubles
List of integers		SafeArray (Vector) of Integers
Property or Linear List		SafeArray (Vector) of Variants
VOID	VOID	Missing value
Parent Script Instance		Depends on 'Value' property
VbScriptXtra wrapper		Automation object
BinaryXtra wrapper		SafeArray (Vector) of Bytes

Director String values are MBCS text. It is converted to Unicode by the xtra. Text conversion routine uses CodePage setting of the wrapper instance that requested the conversion. The code page number directly affects the result of text conversion. Take care when changing the default value of this property, since inappropriate code page number may result in empty string as a result of conversion.

The Symbol type is native to Director, COM knows nothing about it. The actual integer value of any symbol is guaranteed to be the same only during current Director session. So, typecasting routine of VbScriptXtra converts Lingo symbol value into the corresponding string, except cases listed in the table. So value #SomeSymbol will be converted to string "SomeSymbol".

The symbol value #Null is treated as COM Automation Null value. It is often used in databases and in VB to mark empty references to objects.

Symbols #True and #False are converted into corresponding Boolean values. Note the difference between symbol #True and Lingo constant value true. In Lingo value true is the same as Integer value 1, so it is converted as Integer value by VbScriptXtra. Sometimes, it may be important to pass exactly Boolean value to the Automation object. That is why special processing of symbols #True and #False was added to the VbScriptXtra since version 1.02.000.

Special note about Date values. The Date/Time value in COM Automation is actually represented as a float number where the whole part is the number of days since the 1st of January 1901, and the fraction part represents the time. Director uses its own Date/Time values. VbScriptXtra provides a conversion of these values into COM date/time values, but due to a bug in Director 8, the conversion gets the wrong results if the date value is outside this range: date(1901,12,14) to date(2038,1,19). Conversion of date values inside this range works correctly. Director 7.02 and Director 8.5 works correctly over all time period available to COM Automation.

Both linear lists and property lists are converted into SafeArray values. The current VbScriptXtra version supports conversion only one dimension arrays. So conversion will fail if Lingo list contains sub list. Inverse conversion works without this limitation.
Note: SafeArrays may differ by type of its element. Since version 1.00.005r01 VbScriptXtra scans the Lingo list and see whether list entries all have unique data type (either integer or float). If VbScriptXtra detects that all list entries are of unique type it creates a SafeArray of that type. Otherwise it creates a SafeArray of Variants.
Note: VbScriptXtra creates a SafeArray with lower bound set to zero.

VOID Lingo values are usually treated as missing argument, therefore it is converted into corresponding COM Automation value which indicates missing argument.

Other VbScriptXtra wrapper as an argument is converted to the corresponding wrapped automation object reference. So you can safely use VbScriptXtra wrappers with corresponding automation objects where other objects expect them.

VbScriptXtra supports arguments passed by reference through parent script instances. Once wrapper encounters such argument it will use its 'Value' property as an actual argument of the automation object's method. Then after method is executed wrapper will put the updated argument value to 'value' property of the parent script instance.
So, if you expecting modified argument value you will have to create a simple parent script instance, set its value property with actual argument value, use that instance as an argument to wrapper object's method and then get the updated value from that instance.

VbScriptXtra can handle large binary data contained in BinaryXtra wrapper. If such wrapper is passed as an argument, its data is converted to the SafeArray of unsigned chars. For more information about BinaryXtra see its documentation.

Mapping COM Automation types to Lingo types

This conversion is taking place when VbScriptXtra wrapper returns any value returned by the wrapped automation object and when updating arguments passed by reference. This includes getting property values of the wrapped automation object.
The table below describes COM Automation types which are recognized by VbScriptXtra wrapper and into which Lingo types they are converted.

Automation type	Lingo type	Value (if any)
EMPTY	VOID	VOID
NULL	Symbol	#Null
Integer (signed/unsigned), 1,2,4 bytes	Integer
Float 4,8 bytes	Float
Numeric	Float
Date	Float
String	String
Boolean	Integer	1 or 0
Currency	Float
GUID	String
SafeArray of Variants	Linear List
Automation object	VbScriptXtra wrapper
SafeArray of Bytes (BLOB, OLE, Image)	BinaryXtra wrapper

Director String values are MBCS text. COM Automation object uses Unicode as a text encoding. Unicode text is converted to MBCS by the xtra. Text conversion routine uses CodePage setting of the wrapper instance that requested the conversion. The code page number directly affects the result of text conversion. Take care when changing the default value of this property, since inappropriate code page number may result in empty string as a result of conversion.

Empty COM Automation values are converted to the VOID Lingo values.

Null value, which is often used in databases and in VB to mark empty references to objects, is converted to Lingo symbol #Null.

Any integer values are converted to 4 byte signed Integer value native to Director.

Any float or numeric or currency values are converted to 8-byte float value native to Director.

Boolean value in COM Automation usually represented as -1 for true and 0 for false. It is converted to integer values 1 and 0 accordingly.

GUID values are converted in string representation and then are converted into Lingo string values.

SafeArrays of Variants of any depth are converted to the lists of lists of lists... with the corresponding depth.

If Automation object returns a reference to another Automation object, the new VbScriptXtra wrapper is created and initialized with this reference. The new wrapper is returned to Lingo.

Date values are converted to the corresponding float values. Advanced date/time conversion routines will be available soon.

SafeArrays of Bytes (BLOB, OLE or Image database fields) are converted to the BinaryXtra wrappers containing those binary data. This conversion works if BinaryXtra is detected, otherwise 'Cannot convert COM value to Lingo value' error is reported. BinaryXtra is free. It is available in Downloads section. For more information about BinaryXtra see its documentation.