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 the chapter on 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.
Table 16-7 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 Technical Library CD or
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, Table 16-8 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
|
||
| 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 the chapter on MobiLink synchronization in Application
Techniques
.
To test the synchronization objects, complete the following
steps:
- Run the wizard.
- Call synchronization objects
from your application. - Deploy the application and
database files. - Start the MobiLink server.
- Run the application.
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
-
Select File>New from the PowerBuilder menu
bar. -
Click the Database tab, select the ASA MobiLink
Synchronization wizard, and click OK. -
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.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. -
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):
|
1 |
syncparm s_opt<br />gf_<i>appname</i>_sync(s_opt) |
Add the following code to the Clicked event of the Sync Options
menu item:
|
1 |
gf_<i>appname</i>_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 the chapter on 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.