In this article, we'll examine the ScriptENGINE ADO Extension and learn how to manage a database.

We'll be introducing two important ScriptENGINE features:

1) Loading and using DLL Extensions, 2) Using the ADO Extension to communicate with a database.

 

View the Demo Code

The demos are included in the ScriptENGINE SDK. Now's a great time to get the ScriptENGINE SDK from our website (including the SciTE code editor, Programmer's Reference and ScriptENGINE Demos).

Navigate to the ScriptENGINE SDK/[Database] Using the ADO extension folder for the example.

Open the world.e76script in the SciTE code editor. We will be referring to the world.e76script for the rest of this article.

 

The ScriptENGINE Demo Framework

The ScriptENGINE Demos are run using the runDemo.e76script framework code in the ScriptENGINE SDK/Demos folder.

 

Initialisation Code: The OnWorldLoad() function

The runDemo.e76script framework calls the OnWorldLoad() function after it loads the 3D World. This gives the demo a chance to perform any specific initialisation.

The IApp:loadExtension() function loads an extension into the ScriptENGINE. On success, it returns an identifier that can be used with IApp:unloadExtension(). More info about theScriptENGINE Extensions is included in the ScriptENGINE Programmer's Reference.

Loading the ADO extension adds the IAdo interface to the ScriptENGINE. It's used to control the ADO extension.

Create database connection:

The first thing you must do is create a database connection. The IAdo:createConnection() creates a database connection object and returns the new object on success. The internal resources allocated for each connection must be released when you're finishedby setting the object reference to nil.

Set database properties:

Set any database access modes using the IApp:setMode() function to control how the shared resource is accessed.

Open connection:

Use the IAdoConnection:open() function to open a database connection. Pass in the database connection string referring to the database that you want to connect. Database connection strings can be a complicated nut to crack but you'll find a lot of information on the internet dedicated to this specific topic.

Create recordsets:

A recordset can be thought of as a table of records returned from a database query. Multiple recordsets can be opened simultaneously on the one database connection. The IApp:createRecordset() function is used to create a recordset for usewith the ADO extension.

Load GUI:

After successfully initialising the ADO extension, we call IGraphics:loadGui('database') to load the initial GUI controls used with this example (A GUI editor is supplied with the ScriptENGINE SDK).

A GUI subscriber is created to respond to GUI events. The IEvents:subscribeGui('OnGui') function returns the new subscriber identifier. Use the subscriber id with IEvents:unsubscribe() to stop handling the events. The subscribeGui() functions takes the name of the callback function as a parameter. This function must be defined in your script.

Callback function signatures can be found in the ScriptENGINE Programmer's Reference and are also included in the SciTE code editor supplied with the SDK.

 

Cleanup Code: The OnWorldUnload() function

The runDemo.e76script framework calls the OnWorldUnload() function before it unloads the 3D World. This gives the demo a chance to perform any specific cleanup.

 

The GUI Subscriber: Handling GUI events

The OnGui(callerId, eventType, userData) function is used to process GUI events like user button clicks. The actual GUI controls for this example were originally created with the ScriptENGINE SDK Editor, and saved to *.e76gui files. Each GUI definition is loaded into the ScriptENGINE using the IGraphics:loadGui() function and can be saved using the IGraphics:saveGui() function.

When a GUI event occurs, your GUI callback function is passed parameters to inform you what event occurred (eventType) and what GUI control initiated the event (callerId).

We check these parameters using the IGraphics event utility functions to determine what event just occurred and respond as required.

 

Stopping the Demo

The GUI subscriber stops the ScriptENGINE IApp:run() auto-processing loop using IGraphics:stop() after the user clicks the Back button (callerId='btnBack'). Note: This function has been deprecated and replaced with the IApp:stop() function and we recommend the use of IApp:stop() in your own programs.

 

The IAdoRecordset interface

The remaining functions in this example perform specific actions in response to the user GUI input. We will only refer to one in this article but suggest that you take a look at all the functions to learn how this example has been structured.

The loadCompanyData() function opens a recordset on the database connection by creating an SQL SELECT query to grab all the records in the Company table.

If the data is available, then we update the GUI controls on the screen to display the data to the user. If no data is available, then we display an error.

 

The ScriptENGINE Programmer's Reference

We recommend reading the ADO Extension programmer's reference, including information on the IAdo, IAdoConnection and IAdoRecordset interfaces to learn more about the available functions.

 

Side Note: Alternative databasing method using COM

As a side note, the luacom extension can be used to manage databases instead of using this ADO extension. It's a 3rd party library used with the ScriptENGINE to control with Microsoft COM interfaces.

We have included the luacom PDF documentation as part of the ScriptENGINE Programmer's Reference but we don't provide any technical support for this extension.