ADOxtra for Macromedia Director

ADOxtra emulates VB syntax as close as possible

ADOxtra extends the functionality of Lingo to allow you to use ADO right from Lingo. ADO is implemented via COM Automation technology and was designed mostly for Visual Basic clients. VB syntax is native for ADO. ADOxtra tries to emulate Vb syntax as close as possible with Lingo. See more details about differences between real VB syntax and Lingo syntax using ADOxtra in reference section.

ADOxtra provides wrapper instances for every ADO object

ADOxtra extensively uses Lingo's dot syntax to allow cascading access to ADO object's methods and properties. VbScriptXtra provides its own wrapper instance for every ADO object reference. You may think about such wrappers as just Lingo value of some special type. Any method or property access of the automation object is implemented through this wrapper.
CreateObject method is the main starting point while using ADOxtra. Like its Visual Basic analogue, this method creates a new instance of the ADO object and returns it as a Lingo value. This Lingo value is provided by ADOxtra to allow direct access to the object's methods and properties.

Use CreateObject to start databasing

CreateObject is implemented by ADOxtra as xtra-level method. So it can be called only in xtra context. This is done intentionally to avoid possible conflicts with other xtras, which may use the same method's name. So Lingo allows you to either place xtra reference as the first argument of the method or use dot syntax. Following lines does the same:
rst=CreateObject(xtra "ADOxtra",#Recordset)
or
rst=xtra("ADOxtra").CreateObject(#Recordset)

The returned Lingo value is actually an ADOxtra instance, which wraps an ADO object. This ADOxtra wrapper passes onto wrapped ADO object the corresponding method and property calls and makes all necessary type casting.

Several notes, before you begin

ADO objects use a large amount of constant values (enumeration constants) as values of properties and function parameters. For example, Recordset.LockType property may accept several numeric values that indicate the type of locking to be applied to the recordset. These numeric values have their own names (like adLockReadOnly which equals 1). You may use numeric values directly or make ADOxtra to convert constant name to the corresponding value. Every ADOxtra object wrapper has this capability. Just use the name of constant value as usual object's property:
rst.CursorType=rst.adOpenKeyset
It is the same as:
rst.CursorType=1

Also, many ADO parameters or properties may accept or return a bitmask of constant values. Use Lingo bitwise operations to set or get necessary information (bitOr(arg1,arg2), bitAnd(arg1,arg2)).

Several ADO objects' methods may use optional arguments. To skip optional argument at the end of argument list you may just omit it. To skip optional argument in the middle of the argument list use VOID instead. For example:
rst.Open("SomeTable",void,void,void,rst.adCmdTable)

ADO objects use several collections. Collection is just a list of items. For example, Recordset object contains a collection of Field objects. In Visual Basic you may use several approaches to get the certain item in collection. The most common way is Item(index) method of the collection. ADOxtra does not support Item() method due to some syntax limitations in Director 7. Instead, ADOxtra offers square brackets [] operator to access an item of the collection. For example, use:
put rst.Fields["Name"] -- getting the default Value property
put rst.Fields["Name"].Type -- getting the type property of Field object
to access collection items. Another collection supported by ADOxtra is Properties collection of Connection and Recordset objects. Also ADOxtra has limited support for Connection.Errors collection