Using the ASA MobiLink synchronization wizard

About MobiLink

MobiLink™ is a session-based synchronization system that allows two-way synchronization between a main database, called the consolidated database, and multiple remote databases. The ASA MobiLink Synchronization wizard on the Database tab of the New dialog box creates objects that facilitate control of database synchronization from a PowerBuilder application.

This section describes the MobiLink synchronization wizard and the objects it creates. For more detailed information about synchronization from PowerBuilder applications, including information about creating consolidated and remote databases, as well as synchronization objects without using the wizard, see Using MobiLink Synchronization in Application Techniques.

What the wizard generates

You use the ASA MobiLink Synchronization wizard to create a nonvisual user object and a global external function that invokes the MobiLink dbmlsync executable. By default, the wizard also adds two windows and a second global function, but these objects are optional.

The wizard-generated objects make it easier to add database synchronization capabilities to a PowerBuilder target. A structure that inherits from the PowerBuilder SyncParm object is also instantiated by default by one of the wizard-generated global functions. The SyncParm structure is used to hold sensitive database connection parameters entered by an end user in the synchronization options window.

The following table shows objects that can be generated by the wizard, listed by their default names, where appname stands for the name of the current application.

Default name

Description

nvo_appname_mlsync

An instance of the MLSync standard class user object that starts synchronization from the remote client.

gf_appname_sync

Global function that instantiates nvo_appname_mlsync to start the synchronization. This function includes the logic to start the synchronization with or without a feedback window.

w_appname_syncprogress

Optional feedback window that can be used to display synchronization status to the client.

gf_appname_configure_sync

Optional global function that calls the w_appname_sync_options window, which allows the user to configure the dbmlsync client before invoking the dbmlsync executable.

w_appname_sync_options

Window that allows the application user to change connection arguments at runtime.


Using a desktop database profile

Some information that you enter in the wizard is optional, but other information is required. The wizard prompts you for a database profile, which it uses to establish a connection to a remote database on the development computer. If you are not testing a connection on the desktop, you can select the option to proceed without a database connection and ignore the database profile field.

A database profile is required for automatic retrieval of publication names in the database. A publication is a database object describing data to be synchronized. A publication, along with a synchronization user name and a synchronization subscription, is required for MobiLink synchronization.

Selecting publication names

The wizard lets you select multiple publication names if they exist in the remote database defined by the connection profile. There must be subscriptions associated with the publication in order for them to display in the publication selection list.

If you selected the option to proceed without a database connection, the wizard prompts you to type a publication name (or a comma-separated list of publication names) in the MobiLink Client Publication wizard page instead of prompting you to select publication names retrieved from the database.

For more information about publications, see MobiLink - Client Administration on the SQL Anywhere online Help.

Overriding registry settings on the client computer

By default, information you enter in the wizard is saved in properties of the nvo_appname_mlsync user object that the wizard generates. This information includes values that you select for MobiLink logging and command line options and the MobiLink server and port. Prior to synchronization, the values of these properties can be modified with values entered by an application user in the w_appname_sync_options Options window.

The first time synchronization is run, user object property values are entered into the client computer registry. The next time the application is run, this information is available for retrieval from the registry.

The ASA MobiLink Synchronization wizard has an optional Override Registry Settings screen that allows you to override client registry settings. When you enable runtime overrides to the client registry settings, you must assign a build number to the objects generated by the wizard.

The build number you assign can be any positive numeric value. To override the registry settings, the build number you assign must be higher than the build number in the registry, if there is one. Registry settings will be used if the build number in the registry is equal to or lower than the build number in the ObjectRevision property of the nvo_appname_mlsync user object that the wizard generates.

Security measure

For security reasons, the MobiLink user name and password, and the authentication parameters and encryption key database settings are never saved to the registry.

The Override Registry Settings page of the wizard displays only if you do not change the radio button option to prompt the application user for password and runtime changes on the previous wizard page (Optional Runtime Configuration Objects). If, however, you change the radio button selection to disallow runtime overrides to the synchronization, the wizard does not display the Override Registry Settings page and does not generate the w_appname_sync_options Options window.

Wizard options

Except for the object name settings, the following table lists the ASA MobiLink Synchronization wizard options.

Option

Description

Destination library

Lets you select the target PBL file where you want to generate the MobiLink synchronization objects.

Desktop database connection

Lets you select a PowerBuilder database profile or proceed without a database connection.

Publication name

Lets you select a publication (or multiple publications) if you specified a database profile for a desktop database connection. If you did not, you can type the name of a publication you want to synchronize.

Override registry settings

Lets you override client registry settings with values that you (or application users) select for MobiLink logging and command line options, and the MobiLink server and port for the application

Client logging options

Specifies what information gets written to the synchronization log and whether you save the information to a log file.

Additional command line options

Adds the options you specify to the command line for starting the MobiLink synchronization client. You can click the Usage button to see a list of valid options.

Extended options

Adds extended options you specify. You do not need to enter the "-e" switch for extended options in this field. You can click the Usage button to see a list of valid extended options.

Single quotes must be used for any extended option values requiring quotation marks. You must separate multiple options with semicolons; for example:

scn=on;adr='host=localhost;port=2439'

Host

Sets the host information for connecting to the MobiLink synchronization server. If you enter a value for this field, it overrides any value set in synchronization subscriptions and in the Extended Options field.

Port

Sets the port for connecting to the MobiLink synchronization server. The default port for MobiLink is 2439. The value you enter for this field overrides any value set in synchronization subscriptions and in the Extended Options field.


Trying out MobiLink synchronization

This section describes how to try out the ASA MobiLink Synchronization wizard in a sample application. To get started, create a new workspace and a template application. You do not need to create a SQL database connection, but you do need to create a project.

Before you use the wizard to generate objects for the application, you need to set up a remote database and add at least one publication, user, and subscription to it, and create a PowerBuilder database profile for the remote database. To test the synchronization objects from your application, you need to set up a consolidated database. You can create your own remote and consolidated databases, as described in Using MobiLink Synchronization in Application Techniques.

To test the synchronization objects, complete the following steps:

Run the wizard

You start the wizard from the Database tab of the New dialog box. The wizard prompts you for a database profile and a publication, although you can enter this information at a later time after you generate synchronization objects.

To run the MobiLink synchronization wizard

  1. Select File>New from the PowerBuilder menu bar.

  2. Click the Database tab, select the ASA MobiLink Synchronization wizard, and click OK.

  3. Follow the instructions in the wizard, providing the information the wizard needs.

    For help using the wizard, place the mouse pointer in any wizard field and press F1.

  4. On the last page of the wizard, make sure the Generate To-Do List check box is selected if you want the wizard to add items to the To-Do List to guide and facilitate your development work.

  5. When you are satisfied with your choices in the wizard, click Finish.

    The wizard generates objects that you can use for database synchronization.

Call synchronization objects from your application

Open a menu for your application in the Menu painter and add two submenu items to the File menu, called Synchronize and Sync Options. Add the following code to the Clicked event of the Synchronize menu item (appname is the name of your application):

syncparm s_opt
gf_appname_sync(s_opt)

Add the following code to the Clicked event of the Sync Options menu item:

gf_appname_configure_sync()

Deploy the application and database files

Use the Project painter to deploy the application to the desktop and copy this to all computers that will be connecting remotely to the MobiLink server. You need to copy the remote database to all end-user computers, and either register the database as an ODBC database or include connection parameters in a data source name (DSN) file.

For information on additional files and registry entries required on end-user computers, see Using MobiLink Synchronization in Application Techniques.

Start the MobiLink server

Select MobiLink Synchronization Server from the Utilities folder in the Database painter. Fill in the required information and click OK to start the server.

For more information, see Starting the MobiLink synchronization server.

Run the application

Run the application on the remote computer and select the File>Synchronize and File>Sync Options menu items to test their operation.