Altova MobileTogether Designer

The DB Read Structure action enables data to be read from a specified database and stored in a page source named $MT_DBSTRUCTURE. This page source is filled exclusively by data that is obtained when the DB Read Structure action is executed.

Defining the DB Read Structure action

When the DB Read Structure action is dropped in the Event pane, a $MT_DBSTRUCTURE page source is added to the design (visible in the Page Sources Pane). The DB that will be read is defined in the action's settings (screenshot below). These settings are described below.

Read structure from

Specifies the location of the DB structure; solution or server. The structure can be one of the DB page sources in the solution, or it can be a DB that is accessed via a connection stored on MobileTogether Server. For information about stored DB connections, see the description of server-side DB connections in the MobileTogether Server user manual.

Note: Server-side DB connections are available only on Windows-based MobileTogether Servers. As a result, on Linux-based or macOS-based MobileTogether Servers, you are restricted to reading DB structures that are contained in the solution.

Connection name

The connection name can be entered as an XPath string value (see screenshot below). If the structure's location has been specified to be the solution (see previous point), then the connection name is also available for selection in a combo box.

Read Actual/Possible Structure:

The $MT_DBSTRUCTURE page source has a structure that is a superset containing components that are available across various types of DBs.

•Read Actual Structure: Reads the structure of the given DB connection. You can select components to read, as well as filter these components by name (see screenshot above).

•Read Possible Structure: That subset of nodes of the $MT_DBSTRUCTURE page source will be filled that matches the structure of the given DB connection and for which data can be returned. Tables of the DB structure read in this way are not identified by their names.

Filter

This option is displayed only if the Read Actual Structure option (see previous option) is selected. It enables you to filter what DB components to read. You can filter the components in one of the following ways:

•By Selection: Select the check boxes of the components to be read (see screenshot above). To further filter the selected component by name, specify an XPath expression which is a sequence of strings that gives the names of the component to be read. If a particular component has ancestor-type components, then the ancestor-type components will automatically also be read. For example, if a column has been selected, then the column's table ancestor will automatically also be read.

•By XPath: The XPath expression must be a sequence of arrays (see screenshot below). The first item in each array is the component type to read (tables, columns, etc); these items are known as keywords, and available keywords are displayed in a popup that appears when you hover over the option's XPath button; keywords are case-insensitive. The subsequent items of the array (second item onwards) are the names of that component type to read. For example, in the XPath expression shown in the screenshot below, the columns named Author and Publisher of tables named Book are read.

Error processing

The On Error option lets you define what should be done if an error occurs. Since the error handling can be precisely defined for this action, errors on such actions (that provide error handling) are treated as warnings—and not errors. The advantage is that you do not need to check errors on actions for which error handling has already been defined. The following error handling options are available:

•Abort Script: After an error occurs, all subsequent actions of the triggered event are terminated. This is the default action if an error occurs. If you wish to continue despite an error, select either the Continue or Throw option.

•Continue: Actions are not terminated. Instead, you can select what to do in either event: when there is no error (On Success), or when there is an error (On Error). For example, you might want to display a message box saying whether a page load was successful or not.

•Throw: If an error is detected, this option throws an exception that is stored in the Try/Catch action's variable. The Catch part of the Try/Catch action is used to specify what action to take if an error occurs. If no error occurs, then the next action is processed. See the section Try/Catch action for details.

What happens at runtime

At runtime, the specified DB is read, and the nodes of the $MT_DBSTRUCTURE page source are filled with data from the DB. The data in this page source can now be used in the design.

Simulations

If you use the server for simulation, make sure that the server settings in MobileTogether Designer are correctly set and that the DB is available in the server side solution's working directory. See the section Simulation on Server for more information.

If you run a simulation directly in MobileTogether Designer, the data that will be used in the simulation will come from the DB that is specified in the Read DB-Structure Simulation setting (which is available in the Simulation 2 tab of the Options dialog).

MobileTogether extension functions

MobileTogether provides a range of XPath extension functions that have been specifically created for use in MobileTogether designs. Some functions can be particularly useful with specific actions. For example, mt-available-languages() returns the languages in which the solution is available and could, for example, be used with the Message Box action. If a function is especially relevant to this action, it is listed below. For a full list of extension functions and their descriptions, see the topic MobileTogether Extension Functions.

mt-available-db-connection-names()

mt-db-any-changed-fields()

mt-db-any-changed-rows()

mt-db-deleted-original-fields()

mt-db-deleted-original-rows()

mt-db-file-path()

mt-db-modified-fields()

mt-db-modified-rows()

mt-db-new-fields()

mt-db-new-rows()

mt-db-original row()

mt-external-error-code()

mt-external-error-text()