Using the synchronization objects in your application – PB Docs 125

Properties of the user object

The nvo_appname_mlsync user
object contains properties that represent specific dbmlsync arguments,
including the publication name, the MobiLink server host name and
port, and the user name and password for a connection to the remote
database.

When you run the wizard, the values that you specify for these
properties are set as default values in the script for the constructor
event of the user object. They are also set in the Windows registry
on the development computer in HKEY_CURRENT_USERSoftwareSybasePowerBuilder12.5appname
MobiLink,
where appname is the name of your application.

At runtime, the constructor event script gets the values of
the properties from the registry on the remote machine. If they
cannot be obtained from the registry, or if you override the registry
settings, the default value supplied in the script is used instead
and is written to the registry.

You can change the default values in the event script, and
you can let the user change the registry values at runtime by providing
a menu item that opens the w_appname_sync_options window.

Launching dbmlsync

To enable the user to launch a synchronization process, code
a button or menu event script to call the gf_appname_sync global
function. This function creates an instance of the nvo_appname_mlsync user
object, and the user object’s constructor event script
sets the appnameMobiLink key in the
registry of the remote machine.

If you specified in the wizard that the progress window should
display, the global function opens the progress window, whose ue_postopen event
calls the nvo_appname_mlsync user
object’s synchronize function; otherwise, the global function
calls the synchronize function. The synchronize
function launches dbmlsync as an external process.

Supplying a MobiLink user name and password

The global function takes a structure for its only argument.
You can pass a system SyncParm structure that you instantiate. The
structure includes six variables with string datatypes (one each
for MobiLink and remote database user names and passwords, as well
as variables for the authentication parameters and the encryption
key) and another variable that takes a long datatype for a return
code.

If you assign valid values to the structure that you pass
as an argument, the global function passes these values to the user
object to enable MobiLink server and remote database connections.

The options window (described in “Default tab pages of the
options window”) provides a mechanism to store
certain of these values in the registry the first time a user starts
a synchronization. (Sensitive password and encryption information
is never saved to the registry.) Subsequent synchronizations can
be started without the user having to reenter the information, however,
the options window can still be used to override and reset the registry
values.

Retrieving data after synchronization

After synchronizing, you would typically test for synchronization
errors, then retrieve data from the newly synchronized database.
For example:

Capturing dbmlsync messages

The PowerBuilder VM traps messages from the dbmlsync process
and triggers events in the user object as the synchronization process
runs.

These events are triggered before synchronization begins as
the upload stream is prepared:

• ue_begin_logscan
  ( long rescan_log )

• ue_progress_info ( long progress_index,
  long progress_max )

• ue_end_logscan ( )

These events correspond to events on the synchronization server,
as described in “Connection events”:

• ue_begin_sync ( string user_name,
  string pub_names)

• ue_connect_MobiLink (
  )

• ue_begin_upload ( )

• ue_end_upload ( )

• ue_begin_download ( )

• ue_end_download ( long upsert_rows,
  long delete_rows )

• ue_disconnect_MobiLink(
  )

• ue_end_sync ( long status_code )

These events are triggered after ue_end_upload and
before ue_begin_download:

• ue_wait_for_upload_ack
  ( )

• ue_upload_ack ( long upload_status )

These events are triggered when various messages are sent
by the server:

• ue_error_msg
  ( string error_msg )

• ue_warning_msg ( string warning_msg )

• ue_file_msg ( string file_msg )

• ue_display_msg ( string display_msg )

Cancelling synchronization

The Cancel button on the progress window calls the cancelsync user
object function to cancel the synchronization process. If your application
does not use the progress window, you can call this function in
an event script elsewhere in your application.