Lesson 7 - Dictionary Synchronization

Top  Previous  Next

This lesson introduces you to the Clarion Dictionary Synchronizer. It takes you through all the steps needed to synchronize two databases—both the data and the data definitions (.dct, .ddf, or SQL script).

This synchronization process saves time in several development contexts: developing new applications to serve legacy databases, updating existing applications to conform to a modified database, and sharing application development among several developers with incremental modifications to the database definition.


Lesson Objectives

This lesson introduces you to the Clarion Dictionary Synchronizer. When you have finished the lesson you should be able to


Consolidate two Clarion data dictionaries


Run the Synchronizer Wizard


Convert existing data to a new format


Create and review a Dictionary Synchronizer log


Create a Clarion Data Dictionary from a Btrieve or SQL database


To complete the lesson you will need a copy of the files from the Clarion …\Lessons\SyncLesson\Start folder.

Please copy the files to the …\Lessons\SyncLesson folder.


In Windows XP, the Lessons folder is found in:

C:\Documents and Settings\All Users\Documents\SoftVelocity\Clarion7\Lessons


In Vista and Windows 7:



Consolidate Two Clarion Data Dictionaries

In a team development environment, the Dictionary Synchronizer automates the synchronization of the "master" dictionary or database with other project dictionaries and databases.

This section of the lesson shows how to consolidate two similar but different Clarion data dictionaries into a single dictionary. In this example, the master.dct represents the "master" dictionary and the Project.dct represents another dictionary used by the development team. The two dictionaries must be consolidated into a single dictionary that all team members can use to continue to develop their application components.

By using the Dictionary Synchronizer to update the Project.dct (as opposed to simply replacing it with a copy of the master.dct), you are able to see exactly which dictionary items changed and you can intelligently manage those changes; if both dictionaries have changed, you can incorporate the changes from both dictionaries by synchronizing each dictionary with the other; and finally, the Dictionary Synchronizer can generate a Clarion program to convert your existing data to the new format.


Whenever you consolidate two Clarion dictionaries into a single dictionary, you risk damaging the relationship between the replaced dictionary and its corresponding applications, unless you first export those applications to text (.TXA) format.


Make a Master TXA File

Make a Master.TXA file that you can use to create a master.app that will work with the consolidated dictionary.


Starting Point:

The C:\Clarion7\Lessons\SyncLesson\Master.app file should be opened in the Application Editor.



Choose Application  Export Application To Text, then press the Save button to create Master.txa.


Press the button to save and close the \SyncLesson\Master.app.


Select File  Close  Solution (CTRL+SHIFT+F4) to close the application solution.


Run the Synchronizer Wizard

The Synchronizer Wizard leads you step-by-step through the synchronization process. The wizard allows you to select the Synchronizer Server, the data dictionaries, the dictionary to synchronize (identify source and target), and set rules for matching items (files, fields, keys, etc.) between the dictionaries.


Open Project.DCT.

Every synchronization requires an open Clarion data dictionary (although the dictionary may be a newly created one that is completely empty).

When synchronizing two Clarion data dictionaries, it doesn’t matter which dictionary you open first.


From the DCT Explorer, press the Synchronize button to start the Synchronizer Wizard (save the changes).


The Synchronizer Wizard is displayed.


Verify that the Prompt Detail slider to the More position.


Select the Synchronizer Mode


CLICK on the Next > button to start a new synchronization.

This page lets you rerun a prior synchronization. This page also lets you generate a data conversion program without modifying a data dictionary.


Select the Synchronizer Server

The Clarion Dictionary Server is the default (Synchronize With) server. A Synchronizer Server is a .dll that lets the Dictionary Synchronizer access a Clarion data dictionary or a database/file system such as ORACLE, MSSQL, Btrieve, etc. The Clarion Dictionary server handles all Clarion data dictionaries (regardless of the file driver).


Select the Other Clarion Dictionary


Press the ellipsis (...) button to Select the "other" database or dictionary with the Windows file dialog.

If you choose an SQL, ADO, ODBC, or Btrieve Synchronizer Server, the Synchronizer Wizard prompts you for the logon information needed to connect to the SQL database or for the folder containing the Btrieve .DDF files.




Select the Master.dct, then press the Open button.


Set the Synchronizer Log File

The Synchronizer saves details about each synchronization so you can automatically repeat a synchronization process as often as you need to. You can use the Log Synchronization To field to name the log file that stores the synchronization information. Press the ellipsis button and select the current working directory (C:\Clarion7\Lessons\SyncLesson\SynLog.TXT).



CLICK on the Next > button to continue.


Set the Dictionary to Synchronize (source and target)


CLICK on the From ..\Master.dct To Project.DCT radio button to make Project.DCT the target dictionary.

The Dictionary Synchronizer only modifies the target dictionary. Specify which dictionary is the source and which is the target by clicking the appropriate radio button.

The warning is simply a reminder that for any applications that use a dictionary that will be replaced (copied over), you should export those applications to text (.txa) format before you replace (copy over) the dictionary. A .txa is not necessary if you are simply synchronizing two dictionaries, both of which will survive the synchronization.


CLICK on the Next > button to continue.


Select the Source Files to Synchronize

Select the files, views, and tables within the Clarion data dictionary to include in the synchronization process. The Synchronizer Wizard provides two file lists for the dictionary: on the left is a list of files not synchronized and on the right is a list of files to synchronize. Depending on the database server, the list may show filenames, table names, owner names, etc.


CLICK on the > button to select the Customer file and related files.


CLICK on the Next > button.


CLICK on the >> button to move all the files from the left to the right.

This synchronizes all files from Master.DCT to Project.DCT.


CLICK on the Next > button to continue.


Set the Synchronizer Options


If it’s not already cleared, clear the Generate Data Conversion Program box.

The Dictionary Synchronizer options control how the Synchronizer begins the synchronization. You may change these settings later on in the process (in the Synchronize Dictionaries dialog). See the Dictionary Synchronizer Options for more information on these settings.

This page lets you request a data conversion program to convert existing data to the new format. Also, the Matchings button sets rules for matching dictionary items. The default rules match primarily on file and field names.


CLICK on the Finish button to accept the defaults and continue.


Synchronize Dictionaries Dialog

When you "finish" the Synchronizer Wizard, it loads, analyzes, and compares the two dictionaries, then opens the Synchronize Dictionaries dialog where you complete the synchronization process.



The Synchronize Dictionaries dialog compares the two data dictionaries, item by item and lets you resolve any differences between them.



CLICK the Dictionary item (first item in the list) to select it.

Actions you apply to the selected item cascade to all its children.

The Synchronize Dictionaries dialog uses a "file centric" hierarchical list to compare the dictionaries. Beneath each item in the list, the dialog nests the item’s properties and components (files, fields, keys, relationships, and aliases).

The Synchronize Dictionaries dialog uses color to provide information about the synchronization process:


indicates no action is applied, and the item is either different than its matching item or it has no matching item.


indicates an action is applied and the resulting target item is valid, or no action is applied but none is needed because the items already match and the target item is valid.


indicates an action is applied and the resulting target item is not valid—the target does not support the applied property. Red may also indicate an invalid condition in the source dictionary—you can clean up the source dictionary and resynchronize, or you can ignore the invalid item and complete the current synchronization.


The item is not supported by the target dictionary.

Use the navigation buttons and the corresponding navigation menu items to quickly locate new, changed, or invalid dictionary components.

The Synchronize Dictionaries dialog uses action indicators to show the action applied to each item. Action indicators are at the left side of the Destination (target) column. The question mark ( ? ) indicates no decision as yet.

A gray action indicator indicates a cascaded (or inherited) action—the action was originally applied to a parent (full color indicator) and the child has inherited the action (gray indicator).


Right-click on the Dictionary item (first item in the list), and choose Copy to MoreData from the popup menu to apply the action to the selected items.

The action cascades to all children of the selected item—that is, to all items in the dictionary.

When you select Copy to Project.DCT, the Action Indicator changes to a right arrow ( ) for matched items, and to an exclamation point ( ! ) for unmatched items.

The right arrow ( ) indicates the synchronizer will copy the item’s properties from the source to the target.

The exclamation point ( ! ) indicates the synchronizer will ignore the suggested action for unmatched items. This is because the Copy to action only changes existing items in the target dictionary—it does not add new items.


Press CTRL + Z to undo the Copy to action.

The Action Indicator reverts to the question mark ( ? ) — indicating no decision.

Undo may be applied multiple times. It undoes actions in LIFO (Last In First Out) order.


RIGHT-CLICK the Dictionary item (first item in the list), then choose Merge Into from the popup menu.

When you select Merge Into, the Action Indicator changes to a right arrow ( ) for matched items, and to a plus sign ( + ) for unmatched items. A multi-item indicator on a parent item ( ) indicates different actions for different children. For example, a file may contain both matching fields (right arrow) and new fields (plus sign).

The right arrow ( ) indicates the synchronizer will copy the item’s properties from the source to the target.

The plus sign ( + ) indicates the synchronizer will add the marked items to the target dictionary. This is because the Merge Into action not only changes existing items in the target dictionary, it also adds items.

A gray action indicator indicates a cascaded (or inherited) action—the action was originally applied to a parent (full color indicator) and the child has inherited the action (gray indicator).


Press the OK button to complete the synchronization and update the Project.DCT.

The Dictionary Editor dialog shows the updated Project.DCT.

The Project.DCT now matches the Master.dct.


Press the Save and Close button to close the Project.DCT.

This dictionary now contains all the same information (properties, files, fields, and relationships) as the Master.dct; however, these two .dct files are not identical. The Project.DCT will work with the MoreData.app, and the Master.dct will work with the Master.app, but the converse is not true—the dictionaries are not interchangeable because their internal file, field, and key numbers may be different.


Remake the Master Application

Starting Point:

The Clarion environment should be open.



Choose File  New  Solution, Project or Application (CTRL + SHIFT + N).

The New Project window is displayed:




Select the Clarion for Window Category, and then select the Application from Txa Quick Start


Enter Master in the Application QuickStart Name, change the location to C:\Clarion7\Lessons\SyncLesson, and uncheck the Auto create project subdir box as shown above.


Press the Create button.

This opens the Select TXAFile dialog.


Select Lesson.txa from the list, then press the Open button.


Press the Replace All button when prompted for Procedure name clash.

An Error Editor dialog warns you that the .TXA specifies a different dictionary than the application. Since we just synchronized the two DCT files, this warning can be safely ignored.


Press the Close button to ignore the warning.

You can now make and run the Lesson application using the synchronized Qwktutor.dct, and you can make and run the Qwktutor application with the same Qwktutor.dct!




When you replace a data dictionary, you must take the following steps to preserve the internal relationships between the application and the data dictionary: first, create a text application file (.TXA), then update the data dictionary, finally create a new application (.APP) from the text application file (.TXA).

By using the Dictionary Synchronizer to update the Qwktutor.dct (as opposed to simply replacing it with a copy of the Tutorial.dct), you are able to see exactly which items changed and you can intelligently manage those changes; if both dictionaries have changed, you can incorporate the changes from both dictionaries by synchronizing each dictionary with the other; finally, the Dictionary Synchronizer can generate a Clarion program to convert your existing data to the new data format.



Review the Dictionary Synchronizer Log

The Dictionary Synchronizer creates a log to help with the debugging process and to allow batch synchronizations (see the Batch Synchronization help topic for more information).

For every synchronization, the Dictionary Synchronizer creates a log file with the pathname you specify. This log serves two purposes: it can be used to rerun a synchronization in batch mode, and it should be submitted with any bug reports along with the synchronized data dictionaries to aid in the debugging process.

The synchronization from the first part of this lesson created a log file ..\SyncTutr\SYNLOG.TXT. If you browse this file you will see the following:


CMD(DCT(Clarion Dictionary-C:\Clarion7\Lessons\SyncLesson\Project.DCT))

CMD(DCT(Clarion Dictionary-C:\Clarion7\Lessons\SyncLesson\master.dct))





















! SET_ERROR(Field,Customer:CustNumber,DERIVEDFROM,FldDerivedFreeze)

! SET_ERROR(Field,Customer:CustNumber,FREEZE,FldDerivedFreeze)


! RESET_ERROR(Field,Customer:CustNumber,DERIVEDFROM,FldDerivedFreeze)


! SET_ERROR(Field,Customer:CustNumber,DERIVEDFROM,FldDerivedFreeze)

! SET_ERROR(Field,Customer:CustNumber,FREEZE,FldDerivedFreeze)


! RESET_ERROR(Field,Customer:CustNumber,DERIVEDFROM,FldDerivedFreeze)



If a synchronization fails, the Clarion environment tries to create a log called Clalog.txt in the current directory. Please submit this log, the synlog.txt file, and the synchronized data dictionaries and with your bug reports.

Each Synchronizer Server (Oracle, MSSQL, Pervasive, etc.) calls the corresponding database driver to collect information from the database. Therefore, you can also enable database driver logging to trace the Synchronizer Server calls. For more information see the Debugging your SQL Application topic.


Convert Existing Data to New Format


The Dictionary Synchronizer optionally generates a Clarion program to convert existing data to the new format.


Starting Point:

Open the \SyncLesson\Master.dct with the Clarion environment.


Add a Field to the Master Dictionary


In the DCT Explorer, select the Customer file.


In the Fields Quick View, select the FirstName field, then press the Add button.