SyncData Function

Format

b = syncdata(direction, dictionary_nameʃ, sync_universeʅ);

Description

The syncdata function transfers cases in a CSPro data file between a device and a synchronization server. Before calling syncdata, you must first connect to the server by calling syncconnect.

The function can upload cases from the local device (client) to the server as well as download cases from the server. The direction argument determines which of these operations is performed. It must be one of the following values:

GET: Download any cases that were modified on the server since the last sync and update or add them to the local data file.
PUT: Upload to the server any cases that were modified in the local data file since the last sync.
BOTH: Sync cases in the local data file with the server in both directions (i.e., perform both a GET and a PUT).

The dictionary_name argument must be the name of a data dictionary corresponding to the data file to synchronize. This dictionary must be an external dictionary. CSPro uses the data file that is currently associated with this dictionary, either because it was specified when the application was started or via a call to setfile from application logic.

For synchronization with a CSWeb server, the dictionary must first be uploaded to the server. (See the CSWeb help documentation for more information.)

For peer-to-peer synchronization, the data is written to the file associated with the dictionary of the same name on the device running the server. This means that both devices must have this dictionary added to the currently running CSPro application, either as the main dictionary or as an external dictionary.

By providing an optional string expression for the sync_universe argument, you can limit the cases that are transferred. The universe is matched against the ID items of each of the cases. Only cases whose ID items concatenated together match the universe will be transferred. For example, if the universe is "123" then cases with IDs "1234" and "1235" would be synced but a case with IDs "2345" would not.

The syncdata function keeps track of which cases are transferred each time the client and server are synchronized and uses this information to only transfer cases that have been modified since the last synchronization. This significantly reduces the amount of data transferred and therefore reduces bandwidth and the cost of air time. It also reduces the chance that two interviewers overwrite each other's work by both syncing to the same data file on the server. As long as the two interviewers do not modify the same case at the same time, they may both synchronize to the same server without overwriting each other's data.

The syncdata function is only supported when using CSPro DB or Encrypted CSPro DB data sources. Data sources in the legacy text format may not be synchronized using syncdata but instead can be transferred using the syncfile function. That function always transfers the entire file, however, increasing the amount of data transferred and allowing for one interviewer to overwrite the changes of another.

You can use the synctime function to get the time of the last syncdata call.

Return Value

The function returns a logical value of 1 (true) if the transfer was successful and 0 (false) otherwise.

Example 1

if syncconnect(CSWeb, "https://www.myserver.org/api") then

// send the latest survey data to the server
syncdata(PUT, SURVEY_DICT);

// get the latest assignments lookup file from the server
syncdata(GET, ASSIGNMENTS_DICT);

syncdisconnect();

endif;

Example 2

if syncconnect(Bluetooth) then

// sync data for only the province and district assigned to the interviewer
string assignment_universe = maketext("%v%v", ASSIGNED_PROVINCE, ASSIGNED_DISTRICT);
syncdata(BOTH, CENSUS_DICT, assignment_universe);

syncdisconnect();

endif;