The most common use of the object model is from Mobile Data Studio's built-in Data Script window, which can contain a series of script subroutines that are automatically run whenever certain events occur, such as when a session is received from a mobile device.

Data Script uses the VBScript language from Microsoft.

Each of the 7 event handling subroutines is described below. Note that none of the subroutines are required -- if missing, the effect is the same as if it were an empty subroutine, or a function returning True (necessary to continue normal processing).

In addition to any parameters that are passed to a particular subroutine, the Data Script environment also provides a set of global variables that are always available, and ease access to the application, project and database.

Global Variables

Application

The root Application object.

Database

The project's session Database object.

Project

The Project that owns this Data Script.

Users

The Users object, providing access to the User Database.

Global Functions

CreateObject

The standard VBA CreateObject() function can be used to instantiate objects provided by other system components, to interface with other programs or interact with the filesystem or network.

It takes one parameter:

• className - a string specifying the type of object to create, in the form "appName.className".

It returns the new object, or fails with an error. Remember to use the Set statement to accept the returned object value.

NOTE: You should not use this function to instantiate Mobile Data Studio objects, as they are all available by other means -- see the Global Variables section above.

Event Subroutines and Functions

OnAcceptSession

Sub OnAcceptSession( GUID, UnitID )

This subroutine is run when a mobile device accepts a Session that was sent to it.

The GUID of the session, and the UnitID of the mobile device, are available as parameters. Note that the session corresponding to this GUID may no longer exist on the server, if it was deleted as part of the dispatch.

Note also that if the same session was sent to multiple mobile devices, this subroutine may be called multiple times with the same session GUID but different UnitID's.

This subroutine is called for all successful dispatches, no matter how they were initiated. Sessions can be dispatched manually via the Mobile Data Studio GUI, via script code (see the Session.SendToClient() and Session.SendToAll() methods), and via Data Pathway Incoming XML.

OnDeviceConnected

Sub OnDeviceConnected( UnitID )

This subroutine is run when a mobile device has connected to the server, after it has successfully authenticated with the mobile device password.

Note that this subroutine is run in the Data Script of all projects that are open on the server, but it does not guarantee that this particular project is installed on the mobile device that has connected. However, you can use the Auto Load Projects feature in Mobile Data Studio Settings to automatically install selected projects to all mobile devices.

OnIdle

This subroutine is run periodically while the project is open in Mobile Data Studio.

It takes no parameters.

OnIncomingSession

Function OnIncomingSession ( Session )

This function is run when a Session is received from a mobile device.

It is the first step in the Data Pathway, and runs before all other steps that are enabled in the Pathway (such as output to Excel, HTML, XML, and external databases). The session has also not yet been added to the Database (as that is the last step in the Pathway).

If this function modifies the session, those modifications will be seen by all of the following steps in the Data Pathway, and will be reflected when the session is added to the Database.

Normally this function should return True, to continue processing through the rest of the Data Pathway (which will also add the session to the Database, unless that is disabled).

However it can instead return False, to skip the rest of the Data Pathway.

If you manually send sessions to the Data Pathway from the Database window, they will as usual be processed by this function before continuing to through the other Data Pathway steps.

OnIncomingSessionDeferred

Sub OnIncomingSessionDeferred ( Session )

Where OnIncomingSession() is run before the other steps in the Data Pathway, this subroutine is run after all of the Data Pathway steps have completed successfully.

This means that if the Data Pathway outputs to Excel, HTML, XML or external databases were enabled, they have finished by the time this subroutine runs. The files or rows they created on disk are now accessible, and can be accessed at this time if desired.

If the Data Pathway is configured to store sessions to the Database, that will have occurred now as well. This means that if this subroutine modifies the session data, those modifications will not automatically be visible anywhere, including in the Database window, unless the session is explicitly saved (by calling its Session.Save() method).

Note that this subroutine will run even if OnIncomingSession() returned False, and the other steps in the Data Pathway were skipped.

OnMailerFinished

Sub OnMailerFinished ( Token, ErrorMessage )

This subroutine is run when a Mailer finishes its work, as long as its Token property was set prior to calling its Send method.

The Token associated with the mailer is passed as a parameter, as well as the error message, where an empty error message indicates that the email was sent successfully.

OnSourceSession

Function OnSourceSession ( Session )

This function is run when a Session is imported via Data Pathway Incoming XML.

The Incoming tab of the Data Pathway can configure a local folder to watch for new XML files, which will be automatically imported as new sessions.

This function is the first step in the Incoming Data Pathway, and runs before storing the session in the Database (if enabled in the Pathway), and dispatching the session to one or more mobile devices (if enabled in the Pathway). Thus if this function modifies the session, those modifications will be seen in the Database window and/or in the dispatches to mobile devices.

Return True to continue with the Incoming Data Pathway, or False to end processing.

OnTelegram

Sub OnTelegram ( Telegram )

This subroutine is run when a Telegram is received from a mobile device.

The Telegram point can be used inside projects to enable live communication to and from the server, exchanging data or events without leaving the session. These data packets are represented by Telegram objects.

When a telegram is sent from a mobile device to the server, it can include one or more points from the session that is open on the device. These values are available in the Telegram object, along with a special "TelegramName" value that identifies the point.

The UnitID of the mobile device that sent the telegram is available as the Telegram.UnitID property.

This subroutine does not return a response telegram implicitly, but telegrams can be sent to mobile devices at any time, including from within this subroutine if a response is desired. Create a new telegram with Project.NewTelegram.