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.
The nvo_appname_sync user object contains instance variables 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 instance variables 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_USER\Software\Sybase\PowerBuilder\10.5\appname \MobiLink, where appname is the name of your application.
At runtime, the constructor event script gets the values of the instance variables 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.
The user object’s uf_runsync and uf_runsync_with_window functions use the instance variables as arguments when they launch a dbmlsync process.
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_sync user object, and the user object’s constructor event script sets the appname\MobiLink key in the registry of the remote machine.
If you specified in the wizard that the status window should display, the global function opens the status window, whose ue_postopen event calls the uf_runsync_with_window function; otherwise, the global function calls the uf_runsync function. Both uf_runsync functions launch dbmlsync as an external process using a special function in the PowerBuilder VM.
The global function takes a structure for its only argument. You can pass in the s_appname_sync structure generated by the wizard. The generated structure argument includes four variables with string datatypes (one each for MobiLink and remote database user names and passwords) and a fifth variable that takes a long datatype for a return code. The structure object that is generated by the wizard does not set default values for these variables, so you generally need to provide them.
If you assign valid values to the structure that you pass as an argument, the global function sets the value of the MobiLink server and remote database instance variables to the values supplied. For example, you could code a menu item to open a response window with single-line edit boxes, and pass the user-supplied values to the function in the script for an OK button:
s_appname_sync_parms s_opt
s_opt.is_mluser = sle_mlusr.text
s_opt.is_mlpass = sle_mlpwd.text
s_opt.is_dbuser = sle_dbusr.text
s_opt.is_dbpass = sle_dbpwd.text
if gf_appname_sync(s_opt)<>0 then
MessageBox("Error", "MobiLink Error")
end if
If you pass a structure with null values or empty strings to the global function, the uf_runsync functions of the nvo_appname_sync user object look for MobiLink and database user name and password values stored in the registry. The options window (described in “Using the synchronization options window”) provides a mechanism to store these values in the registry the first time a user starts a synchronization. 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.
After synchronizing, you would typically test for synchronization errors, then retrieve data from the newly synchronized database. For example:
if gf_myapp_sync(s_opt) <> 0 then
MessageBox("Error", "MobiLink error")
else
dw_1.Retrieve()
end if
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 )
The default event scripts created by the wizard trigger corresponding events in the optional status window, if it exists. The window events write the status to the multiline edit control in the status 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.
The Cancel button on the status window calls the uf_cancelsync user object function to cancel the synchronization process. If your application does not use the status window, you can call this function in an event script elsewhere in your application.
