Using the synchronization objects in your application
Before you use the generated objects, you should examine them in
the PowerBuilder painters to understand how they interact. Many of the
function and event scripts contain comments that describe their
purpose.
All the source code is provided so that you have total control
over how your application manages synchronization. You can use the
objects as they are, modify them, or use them as templates for your own
objects.
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_USERSoftwareSybasePowerBuilder21.0appnameMobiLink,
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:
|
1 2 3 4 5 |
if gf_myapp_sync(s_opt) <> 0 then MessageBox("Error", "MobiLink error") else dw_1.Retrieve() end if |
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:
|
1 2 3 |
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:
|
1 2 3 4 5 6 7 8 |
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:
|
1 2 |
ue_wait_for_upload_ack ( ) ue_upload_ack ( long upload_status ) |
These events are triggered when various messages are sent by the
server:
|
1 2 3 4 |
ue_error_msg ( string error_msg ) ue_warning_msg ( string warning_msg ) ue_file_msg ( string file_msg ) ue_display_msg ( string display_msg ) |
The default event scripts created by the wizard trigger
corresponding events in the optional progress window, if it exists. The
window events write the progress to the multiline edit control in the
progress window. Some window events also update a static text control
that displays the phase of the synchronization operation that is
currently running (log scan, upload, or download) and control a
horizontal progress bar showing what percentage of the operation has
completed.
You can also add code to the user object or window events that
will execute at the point in the synchronization process when the
corresponding MobiLink events are triggered. The dbmlsync process sends
the event messages to the controlling PowerBuilder application and waits
until PowerBuilder event processing is completed before
continuing.
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.