Concepts for DB Sync server-side apps

DB Sync server-side apps use the DB Sync API to manage SQL table updates, ensure concurrent data access control, and log changes in the central database. These apps need specific runtime files, must operate within transaction blocks, and handle user permissions and synchronization conflicts to maintain data integrity.

DB Sync server-side apps directly access the central database to update SQL tables that are also used by DB Sync client apps using the DB Sync service.

Server-side apps must use the DB Sync API to register all modifications into the DB Sync central changes log, and get concurrent data access control on the SQL tables shared with the client apps.

The DB Sync API for server-side apps places update SQL locks on the DB Sync configuration table, forcing other processes to wait until the current transaction completes.

The dbsync_srvapp module provides the DB Sync server-side app API.

Important:
When deploying your server or client app program files, make sure to include the required DB Sync runtime files along with your application program files. The following DB Sync runtime files are required:
  • dbsync_core.42m
  • dbsync_err.42m
  • dbsync_app.42m (for DB Sync client apps)
  • dbsync_srvapp.42m (for DB Sync server-side apps)
  • dbsync_login.42f

When a DB Sync API function returns a negative integer, it indicates a failure. The corresponding error message can be retrieved with the dbsync_err.get_error_message(s) function.

The DB Sync server-side app API initializes when you call dbsync_srvapp.initialize(). When ending the program, you must call the dbsync_srvapp.cleanup() function.

Use dbsync_srvapp.register_central_app_params() to load the DB Sync schema and register the app ID and user ID.

In server-side applications, all INSERT/UPDATE/DELETE operations and registration of changes must occur in a transaction block, to revert all changes with ROLLBACK WORK in case of failure, and have SQL locks set during the SQL transaction to prevent other DB Sync clients from updating the same tables.

After BEGIN WORK, call the dbsync_srvapp.central_change_init() to initialize the process and set SQL locks on the dbsync_udsinfo table to block other DB Sync users.

Then perform the INSERT/UPDATE/DELETE operations on the central tables and register all changes with the dbsync_srvapp.register_central_*() functions.

When all changes are complete, call dbsync_srvapp.central_change_done() to end the process, then terminate the SQL transaction with COMMIT WORK.

If central changes fail at some point, call dbsync_srvapp.central_change_cancel() before performing ROLLBACK WORK to cancel the SQL transaction.

To register changes, server-side apps use dbsync_srvapp.register_central_*() functions for each row INSERT, UPDATE, or DELETE. This allows server-side applications to register changes as if client applications performed them.

The function checks user permissions for the specified table, and rejects the change if denied.

By default, the DB Sync server-side app always overrides changes done by DB Sync remote apps, and ignores them.

To check for other user/app changes (including other server-side app users), after loading rows from the database, call the dbsync_srvapp.central_set_sync_timestamp() function to register the point in time of the last data fetch into the application memory. This will set the timestamp of the last data refresh in the current DB Sync server-side app, and check for other user changes when calling dbsync_srvapp.register_central_*() functions for a given row.

If another user has made more recent changes, the registration function will return an error. The DB Sync server-side app code should then fetch new data, re-do the modifications, and re-initiate a central change process taking other user changes into account.