Synchronizing in Procedure Code

To synchronize the current database with the server use the synchronize statement.

    synchronize

This is exactly the same as choosing Synchronize from the File menu (see Shared Database Synchronization).

### Force Synchronization

When Panorama synchronizes with the server, it transfers only the records that have actually changed. These updated records are merged with the existing unchanged records in the local database. A more drastic way to synchronize is called Force Synchronization which transfers the entire database from the server to the local database, including both changed and unchanged records. Here’s how to do this in a procedure:

    forcesynchronize

Theoretically you should never need to do a Force Synchronize, but the option is there if for any reason you think a database is not synchronizing properly. This statement is the same as holding down the Option key when you choose the Synchronize command from the File menu (which converts the menu item to Download Data).

### Automatic Pre and Post Synchronization Procedures

You may want to run a procedure automatically before and/or after each synchronization is performed. For example, you may want to make sure that the database is sorted a certain way after each synchronization, or you may want the current record to remain the same after a synchronization. To make this possible, Panorama checks for two special procedures in your database — `..PreSynchronize` and `..PostSynchronize`. If it finds a `..PreSynchronize` procedure it will run it before the synchronization is performed. If it finds a `..PostSynchronize` procedure it will run after the synchronization is complete.

WARNING: These procedures MUST not display any alert or dialog, and they also must not change the current window or the current database. Do not use statements like alert, rundialog, window or setactivedatabase in these procedures.

When Panorama calls the `..PostSyncrhronize` procedure, it passes a dictionary that tells you what happened during the synchronization process. The values in this dictionary are:

- UPDATEDRECORDS – The number of records that were downloaded from the server during the synchronization, zero if no records were downloaded.

- DELETEDRECORDS – The number of records that were deleted from the local copy of the database during the synchronization process (because they were deleted by another user), or zero if no records were deleted.

- TIMESTAMP – The “time code” of this synchronization. This is not actually a chronological time, but an incrementing value that increases as more and more changes are made to the database.

- NOTIFICATION – The notification message that Panorama normally displays when synchronization is complete. If you supply a `..PostSynchronize` procedure, you are responsible for displaying this message yourself (so you can customize it or not display the message at all.)

- NOTIFICATIONDETAIL – Additional detail for the notification message that Panorama normally displays when synchronization is complete. If you supply a `..PostSynchronize` procedure, you are responsible for displaying this message yourself (so you can customize it or not display the message at all.)

- VERIFICATIONERROR – This value can only appear when automatic verification of synchronization is enabled (see Automatically Verifying Synchronization on the Shared Database Synchronization page). If the verification fails, this value will contain a list of records that failed to match between the client and the server. This list is in an undocumented internal format, but you can use the alerttimestampmismatches statement to display the list in a useful format.

Note: Panorama X handles these parameters differently than Panorama 6 did. If you are porting a Panorama 6 with a `..PostSynchronize` procedure, you will have to rework any code that accessed these parameters to get information from the dictionary instead of from numbered parameters.

#### Using ..PreSynchronize

The `..PreSynchronize` procedure can be used to save status about the database before the synchronization.

For example, here is a typical `..PreSynchronize` procedure that saves the ID of the current record.

    letfileglobal BeforeSyncRecordID = info("serverrecordid")

#### Using ..PostSynchronize

If you also add this `..PostSynchronize` procedure to your database, Panorama will use the findid statement to make sure that the current record is the same before and after the synchronization process (unless the current record has been deleted).

    findid BeforeSyncRecordID

Note: You could instead use the the find or findbackwards statement to restore the position in the database, like this:

    findbackwards BeforeSyncRecordID=info("serverrecordid")

If you also want to display the normal notification when the synchronization is over, here is how to do that in the `..PostSynchronize` procedure:

    let syncInfo = parameter(1)
    let message = getdictionaryvalue(syncInfo,"NOTIFICATION")
    let extramessage = getdictionaryvalue(syncInfo,"NOTIFICATIONDETAIL")
    nsnotify message,"TEXT",extramessage

You could also customize the message if you wish, or even supply a completely different message.

See Also

- Bulk Data Transformations on Shared Databases -- using formulafill, propagate, etc. in a shared environment.
- Controlling and Monitoring the Server Connection -- overriding automatic server connection behavior.
- Looking up Data Directly from the Server -- local in-memory vs. server lookups.
- Record Locking in Procedure Code -- implicit and explicit management of record locking.
- Server Variables (Shared Variables) -- sharing variable values across multiple users.

History

Version | Status | Notes
10.2 | New | New in this version.