With the innovation of new technologies, interest is being diverted away from DOS and the era of DOS continually reaches back. While DOS applications still have their place, Windows applications are nowadays recognized as being the choice since they are more maintainable and supportable, and flexible to evolve to ever-changing business requirements. It would be very unwise to bury the existing DOS applications, and DataEase for DOS (DFD) applications in particular, since without any doubt, investments made in developing and maintaining existing DFD applications and training are considerable. Therefore the task of making the investments work today and upgrading applications has become the barest necessity.

The most natural way of upgrading existing DFD applications is to convert them to DataEase for Windows (DFW) since it is very effective and time sparing. Taking into account the fact that some of the DOS applications might have been created long time ago and poorly maintained or not updated properly, the structure of such applications might have become inconsistent and weedy. It does not matter whether a DFD application is old or not and whether it is in a poor or good condition, it can be successfully converted to DFW using any of the following approaches: creating a DFW application on a one-to-one basis which is low cost and quick to implement or converting the application utilizing technical solutions aimed at optimizing databases that can be achieved by utilizing DFW resources. From our experience, one of the ways that often drastically improves performance is the DFD database normalization (For more information on data normalization, please, see the Spring 2002 issue of the “@Ease Dialogue” magazine.) with minor changes to the database logic.

This document provides an encompassing overview of the proven methodology that can be used for converting DFD applications to DFW, and the conversion best practices and advices. Adherence to these best practices can help you avoid the majority of problems you might encounter. The phases of the conversion process are described chronologically, starting with the preparing an application to moving to DFW and continuing through the proposed solutions and implementation.

Pre-Conversion Jobs

The application you are about to convert can be in either DFD v.4.x or DFD v.5.x. It is on the version number that your further steps depend. Should the application be in DFD v. 4.x, it is considered best practice to upgrade it to DFD v.5.16 because DFD v.5.16 and DFW have similar underlying file structure, which considerably simplifies conversion of the application to DFW. Upgrading a DFD v.4.x application is a simple task that can be done using DFD v.5.16. So the process is DFD 4.x - DFD 5.16 - DFW.

• Store a master copy of the original application safely away in case it should be needed.

Backup and Restore

It is necessary to check that the database as supplied is in good condition, i.e. that it does not have any corruptions or damaged files. The best way to carry out this check is to undertake a backup of the application without data. This backup process should be carried out on the copy of the original application before any further work is done. Restoring the data-less application from the backup copy re-creates the application structure: DFD removes existing references to files that physically no longer exist. The verified for correctness and accuracy application structure should be saved to another folder. It is on this application that all further work will be done.

DOS Application Inventory

The database structure received in the result of the backup-restore operation should undergo thorough inventory. The aim of this step is to get complete information on the database contents (list of the db tables, fields and their attributes, relationships existing between the DFD tables, list of procedures and their elements, menus, list of control procedures, etc.).

The information obtained should be considered as a simple initial guide to redundant elements and can be used as a basis for developing the main working document intended for the in-conversion-team usage that will help track updates and changes to the database. The document should contain minute information on each of the application entities: old names, new names, entity properties (i.e., flags, derivations, destinations, calling objects and so on), notes describing modifications (i.e., date, converter name, notes, problems, etc.) and the like.

The db inventory can be carried out using an in-house or third party utility such as the IncrEase utility that greatly speeds up the inventory.

• You could create an Excel-based workbook, with spreadsheets grouped by entity types (Forms, Procedures, Menus, Fields, etc.).
• Clean up your database. The converter should thoroughly analyse the inventory information and decide which entities stated as redundant are really unnecessary or required. The entities confirmed as unnecessary (for example, menus with empty calls or choices having no action, procedures that will not be used in future, tables never filled with data and so on) should be manually deleted from the DFD database.

Entity renaming

One of the pre-conversion tasks concerns renaming database entities. It is vital to understand why entities need to undergo name changes in the course of conversion. The DFD and DFW database management systems use almost the same list of keywords, also known as reserved words, words that have special meanings to DFD and DFW and that are not good choices for naming database entities such as tables, fields, relationships, forms, procedures, etc. However, some of the DFD application entities, namely, fields or forms, may have names that are identical to keywords. This situation does not prevent DataEase for DOS from running the application correctly, but the DFW naming conventions prohibit using keywords as entity names. Therefore, such entities must be renamed to differentiate them from keywords.

At this stage of the conversion process it is considered best practice to rename only tables of the DFD application because it is much easier to carry out renaming in DOS.

• Renaming DFD entities can be carried out using a third-party utility such as Jada.
• Avoid using spaces in names, but if you have not eliminated spaces in names and encountered problems, enclose such names in quotes.

Getting Started with the Conversion

After the application has undergone inventory and has been pre-processed in DFD, the converter can start working on it in DFW. If you open the application using DFW, you will see that the Catalog lists only those entities that are stored in DFD and DFW similarly: tables, relationships, users, imports and custom functions. The DFD and DFW file format of the other entities, such as procedures, menus, etc. is different. Therefore these entities are not available in DFW but their files retained in the application folder can be confusing to a user and just take up space, so they can be deleted.

• You should delete all non-DFW files from the your application folder. Such files are left over from the DFD and are not required in the DFW application. The files to remove are named: *.cfe , *.cfm, *.dbr, *.tde , *.eNN, where N is a number,menu?aaa.dbm (file containing DFD menus), and the following system entities: conf?aaa.dbm (Configuration file), printers.dat (Printers file) and dict?aaa.dbm (Dictionary file).

Use Style Sheets

DFW uses the concept of Styles. Style is a named set of display attributes (font, text colour, border size, etc.), which can be applied to any visual element of the application (button, text field, label, etc.). Styles define how elements look like: once a style is applied to an element, the element immediately derives all the display attributes of the style. With Styles it is easier for you to make elements of the same kind look the same way, which is one of the GUI consistency requirements. For example, you may create styles for buttons, ordinary text fields, required text fields, labels, etc. and then apply those styles to the corresponding application elements instead of applying repetitive formatting to each of the elements. Styles are grouped and stored in Style Sheets using distinguishable names. For instance, you may create a set of styles, which cover all the element types and save it as My Favourite Styles (physically it will be My Favourite Styles.sty database file, which can be installed and used with any DFW application).

• If you subsequently decide to change the element appearance, simply update the corresponding Style in the relevant Style Sheet. All the elements in your application that use this Style will automatically be updated.
• If you are working on a number of applications having similar structure and/or utilizing common styles, it is very convenient to create a kind of sample styles application, which is in fact a repository of document templates and element styles. Templates of such documents as menus, forms or Data Entry forms can have pre-defined layout of elements and design. When needed, you can install such templates into the application you are working on and modify in compliance with the project requirements.

Do not Forget to Make Backup Copies

It is considered a good practice that you regularly make backup copies of the database not to lose the work previously carried out. Should something go wrong with the later conversion stages, you can always retrieve the latest reserved copy.

Conversion of Tables

In fact, the first thing to start with in DFW is a database structure comprised of tables and relationships between them. At this point all database tables are already available in the Catalog, but it is necessary to ensure the database structure is consistent and ready to use, i.e. fields bear valid names and relationships between related tables are viable.

Taking Control of Tables

DFD v.4.53 treats tables and forms as the same entity and the user having permissions to perform modifications (delete, add records, alter field width and etc.) can modify the table structure by simply accessing the table. The DFD v.5.16 and DFW split forms and tables and treat them as different entities. DFW tables are used to store data that can be viewed via one or more view forms but managed via one table definition form (a form whose Defines Table property is selected). Certainly, a table definition form also can be a view form.

• Uncheck the Document Properties >> Transferable Table property. This ensures that forms ownership can only be transferred from DFW to DFD by a deliberate, rather than an accidental, act.
• In case the Defines Table property is unavailable in DFW, go back to DFD and uncheck the Owned property in the form properties.
• Since DFW as opposed to DFD v.5.16 prohibits using conditional derivation formulas on the Required, Prevent data-entry, Colour fields, remove all conditional derivation formulas on such fields in DFD.

Adjusting Table Structure

The tables renamed in DFD bear valid DFW names but there is no guarantee that table field names will not conflict with the DFW key words and that relationships existing between the tables will work properly: related fields that link tables might need name changing. Therefore the whole structure of each table (field names, derivation/validation formulas and relationships) might need adjusting.

The process of adjusting the table structure is not so trivial as it may seem. It is not enough to just rename table fields. If table field values are derived from other related tables whose fields bear invalid DFW names, DFW will not let you save the table because derivation/validation formulas may contain dead references. Therefore relationships might also need adjusting.

• The algorithm for adjusting a table structure is self-coordinated and offers the following solution:

1. Cut all the derivation/validation formulas and place them on the table definition form as labels next to the corresponding fields;
2. Rename fields and Save the table definition form (table);
3. Edit and rename relationships (use renamed field names in relationships);
4. Adjust derivation/validation formula on each field using renamed relationship and field names and put them back in the field definition window. Save the form (table).

Modifying DOS Long:Text Fields into Memo Fields

A DFW Memo field is a text field that stores and displays text up to 4000 characters. There is no such field type in DFD. A DFD Long:Text field allows the user to enter up to 255 characters. A number of Long:Text fields grouped and arranged one below another lets the DFD user type descriptive information exceeding 255 characters in size, which allows the text to wrap. Each group of DFD Long:Text fields is converted into one DFW Memo field, the size of which is equal to the sum of the Long:Text fields sizes. The memo is saved using the first Long:Text field name in the corresponding group.

• If a form has a large number of fields (the maximum is 254), do not overload the form with memos but rather store their values in sub-tables. In this case you will need to alter procedures that use these newly created sub-form records.

Designing View Forms

A DFW form document allows the user to view and manipulate the data in the underlying table. A form contains such elements as fields, sub-forms used to represent fields of the corresponding sub-table, labels, page header and footer used to enhance the appearance of the page, etc. Table definition forms are designed like any other view form.

• Uncheck Defines Table property for table definition forms before any design just not to accidentally change the table structure. After the design is completed, tick the property again.
• For users convenience the design of each DFW view form should mirror the DFD counterpart design or be created in accordance to the project standards
• When designing view forms, replace any single “&”encountered in labels with double“&&”: it is just a workaround and on the screen you will see the same single “&”. Otherwise the next symbol after “&” will appear underlined and there will be no “&”at all.
• Using clipboard to transfer DFD form labels facilitates the process of designing view forms but elements will lose their styles: you will need to re-apply styles to these elements anew.
• If a DFD form is printed as a report, in DFW you will need to create a special procedure to have the form printed in the same way.
• If several forms have similar design (little differences), you might design one form and then clone it.

Adjustments to a Form Document

Also for users convenience, it is possible to optimise the database by replacing choice lists (anything other than yes/no, male/female, days and months and other invariable sets of values) with special tables, called dictionaries that grow or shrink dynamically. The reasons for doing so are the following:

1. Some of the DFD forms and procedures with Data-Entry forms may use the same choice-lists. If you decide to change a set of entries in one of the form choice-lists, then you will need to manually make the same changes to such choice-lists in all the other forms.
2. All choice-lists have a pre-defined set of entries that can be modified only by the system administrator in the Designer View mode. An ordinary user is unable to modify the set whilst a dictionary can be easily updated by simple record entry.

The process of converting choice-lists includes creating a dictionary table with one field, populating the newly-created table with values retrieved from DFD choice-lists, creating a lookup form to display the dictionary table records, creating a relationship between the view form and the dictionary and replacing choice-lists on the view form with text type fields. Next to the relevant text field on the calling form you should create a button with action telling DFW to open the related lookup form.

DFD-DFW Data Transfer Process

After the structure of the database tables have been adjusted (fields and tables renamed, derivation formulas adjusted, etc.), it is high time to populate the database tables with data. This should be done before you go on to converting such data-connected entities as procedures and forms. The process of transferring data between applications is called Data Transfer. To transfer data you should create special routines both in the DFD database and in DFW. The data transferred to DFW should be identical to the DFD data. In this case you will be able to easily check that the DFW application works exactly the same way as DFD. After the DFW application is completed, the routines built will help transfer the live data from the existing DFD application into the converted DFW database.

The data transfer process comprises of exporting the DFD data into interim text files and importing data from those files to the DFW database.

DFD Export Routines

To export the data from within the original application, the converter creates an export procedure for each DFD application table.

• The easiest way to export the data is to create a QBE report that includes all table fields. Set the report Output Format to Export/Variable Length/Include Field Names and choose a field delimiter most appropriate for your data (i.e., tilde” ~”, grave accent “`”, etc.). Whatever symbol is chosen as the field delimiter, it should be reliable, i.e. there is no such a symbol within the field values. The DataEase Conversion Team offers a special utility that checks the field values for the symbol used as the delimiter.
• After the Output Format is adjusted, edit the line containing field names (the top line in the Output Format Screen): the Output Format Field Names string should contain field names as they are in DFW. This ensures that the data from these fields will be imported into the corresponding DFW fields.
• Set the report Print Style: specify Report Destination of the created export to Disk and specify a name of the output file, unique for each export. Save each export using some standard name (i.e., Expo0001.txt, Expo0002.txt, etc., with Expo0001,Expo0002, etc. being the corresponding export procedure names).
• To provide the customer with the facilities to export all the data from their existing DFD applications at a time, create a control procedure (i.e., ExportAll) that calls individual export procedures and thus will export all of the data from the customer DFD database.

We would like to offer you some practical advices that could help you avoid numerous pitfalls when you create DFD exports.

1. If the symbol used as a delimiter is not reliable, try another symbol and make new exports.
2. If a group of the Long:Text fields has been converted into a DFW memo field, alter the Output Format of the export procedure: in the first Output Format line replace all names of the Long:Text fields with one name of the DFW memo field and remove delimiters between the fields; in the line defining output of field values replace delimiters separating Long:Text fields with spaces: values of several Long:Text fields will be concatenated into one field and exported using one caption that coincides with the destination memo field name.
3. If the data to be exported contain double quotes, such data cannot be imported to DFW one-to-one: framing quotes will be thrown away. But if the value of a field has an odd number of quotes – “Dialogue instead of “Dialogue”– during import the values in line between this quote and the next nearest quote will be concatenated into one value (i.e., the “Dialogue” text value will be imported as Dialogue; the “Dialogue magazine ~2002~Spring string that contains 3 tilde separated values will be imported to DFW as one string). In cases like these you need to decide whether the quotes worth transferring to DFW or could be neglected. If the DFD data contain only framing quotes, in most cases you can throw them away in DFW: the data will not be affected.

• If it is necessary to keep the quotes, then replace quotes with another special symbol ($) when exporting the data from DFD. After the data are imported to DFW tables, replace $ with quotes.

DFW Import Routines

To populate the DFW database, the converter creates a DFW import for each DFW table. The import retrieves data from the corresponding export file into the DFW table.

• Save each import using unique names (i.e., Impo0001, Impo0002, etc.). An import and export names should be descriptive so that you could easily tell they are built for the same table (Expo0001-Impo0001, etc.).
• In the DFW application create two special control procedures: a procedure (i.e., DeleteAll) that deletes the data from within the DFW database and another procedure (i.e., ImportAll) that runs each import in turn and updates the data.

Test of Data Identity

The data imported into the DFW application tables must be compared with the original DFD application data to ensure that the data transfer process is a success. In this step, the DFW application table data are exported into separate text files and put to the same folder where the DFD export files reside.

• Open the table in User View and choose File >> Export. Specify the file name (i.e., Expo0001.dfw) and full path. Use the same delimiter as when exporting the data from DFD and tick the Include Field Names option. Since DFW does not allow you to save the export settings, you will need to tune up each export.

Then these text files are compared using the standard File Compare utility (the executable file is FC.EXE).

• Given that DFD and DFW export files are stored in one folder and their names are identical (i.e., Expo0001.txt and Expo0001.dfw contain the data exported from the same table from DFD and DFW respectively), such file pairs can be compared using one DOS command: FC.EXE *.txt *.dfw > result.txt.

In case the database structure has undergone considerable changes (for example, due to normalization of tables, adding/deleting fields, etc.), there is no chance to get “FC: no differences encountered” as a compare result: explicit differences are inevitable. Each divergence should be accounted for, analyzed and documented.

Building Procedures

Conversion of a procedure comprises of creating a new procedure in DFW and then building each of the procedure elements from scratch (Data-Entry Form, DQL coding and Output Layout). DFD procedures are partly portable to DFW because they utilize the same language DQL. The text below summarizes procedure conversion technology without going into too much technical details because building procedures in DFW is one of the most complex and time-consuming conversion jobs and cannot be described in an article.

Adjusting the DQL Coding

The process of procedure conversion starts with creating a new DFW procedure and copying the DQL coding from the DFD counterpart. Most likely you will need to change the DQL due to the following reasons:

• The names of entities (table, field names and relationships) that might have been renamed earlier and encountered in the DQL should be replaced with correct DFW entity names.
• Some other adjustments take place to obtain the same output layout as in the DFD procedure (more details will be found in the Output to Screen/Printer section).
• Procedures that have several polytypic operators used to modify the same table data (modify, delete, enter a record or reorganize) might lock this table on the network. Therefore, such procedures must be split into separate procedures that perform only one modification to the table.

• In case one of the above-mentioned operators is followed by the list records command, then this list records command should be singled out into a separate procedure.

But the conversion of procedures is not restricted to the aforesaid modifications to the DQL.

Your further actions depend on the type of the converted procedure: whether a procedure generates output to screen/printer or not. If it is a procedure without output (its DQL has no list records command), then it remains only to compile, save it and check its functionality.

In case it is a procedure with output (to screen/printer/disk), it is the output target that has the principal meaning: screen/printer or disk. These two types of procedures are implemented differently in DFW and in each case the conversion should be done using an artful approach.

Output to Screen/Printer

Conversion of such procedures can be a complex task because the DFW output format depends on the procedure DQL more than the DFD procedure output. Upon compilation, DFW automatically creates default output layout for the procedure that is the placement of different output field groups. These groups are defined by the list records command, with the list items grouped using the in groups or all operators. In this case the procedure output will have a multi-layered structure.

The output format of a DFD procedure can be defined after the procedure has been compiled: it is possible to move elements from the captions of groups into group items and vice versa (use copy/paste), but in DFW you may not get the desired result by moving elements between the layers. For example, let us look at the following DQL coding:

for Contracts;

list records

CustomerName in groups ;

CustomerCity ;

ContractNo .

In DFD you can place the CustomerCity and CustomerName fields at one level and get the CustomerCity field value output one time for each group. Moving a field to an upper level in DFW will do no good: the CustomerCity field values will not be printed on the page. The most appropriate solution is to alter the procedure DQL:

for Contracts;

list records

CustomerCity ;

CustomerName in groups ;

ContractNo .

In this case, you will have the fields correctly placed on the report page. In DFD it would be enough to simply move the CustomerName field from the .items area into the .group header area in the procedure format without changing the DQL.

The developers experienced in DFD might find it strange to alter not only the output format but also the procedure DQL in order to change the field placement on the page. But the DFW output is strictly layered: the DQL defines at what layer and where the fields will appear.

To complete the output formatting you will need to arrange the fields at each layer in order and adjust their appearance (colour, font, size, etc.). The format of the elements (width of text values, number of decimal digits, etc.) should be the same as in DFD.

• If a procedure has fields that should not be displayed on the screen (in cases when you sort or group this field values), you can: set the field size to a minimum; move the field beyond the displayed visible area or “hide” the field using the report form background colour as the colour of the field background and font.

Export to Disk

The export to disk procedures should be considered a special case of procedures. Such procedures should write data to a text file. In DFD, a procedure will export data to disk if you specify the Disk destination (Print Style >> Destination >> to Disk). In DFW the situation is different: if you set Document Print Options >> Print to Disk, you will not get a text file with human readable data as desired but a binary file containing an exact image of the printer specific output. To write data to a text file in DFW, append the export to “filename” . command to the procedure text transferred from DFD. The export to command should be followed by the special formatting “.commands” that define the placement of the output data. In general case a DFW export procedure looks like:

for Table1;

list records

Field1 ;

...

FieldN .

end

export to “filename” .

.items Table1

@f[1,1], ... ,@f[1,N]

.end

This is the simplest case of exporting data from within one table – the table data are output line-by-line into a text file. A need to export data from within several tables, groupings, data summarizing in group footers make the task of exporting data much more difficult. Converting such procedures takes much more time as compared to converting similar procedures with output to screen/printer.

Methods to export data to a file in DFW were described in the … issue of the “Dialogue” magazine (“Special Export”). Using these methods you can convert simple export procedures, i.e. procedures either without groupings or with groupings but without subtotals in the group footers output.

In addition to the article, we could suggest using the output operator that helps solve the various problems of exporting table data to disk in text format: it is possible to control export of records by a conditional operator. For example,

define temp “tFld” text 20 .

for Table1;

assign tFld1 := Field1 .

if (some condition) then

output:

tFld1 .

end -- output

end –– if

end -- for

export to “filename” .

.items output1

@f[1,1]

.end

In this example the Field1 value will be written to the file only if the “some condition” is true for the Table1 records.

The list recordsoperator is not so general-purpose means as the output operator. For example, almost the same code:

for Table1;

if (some condition) then

list records

Field1 .

end –– if

end -- for

export to “filename” .

.items Table1

@f[1,1]

.end

will write to the file the Field1 values for all records, no matter whether the “some condition” is true or not. Using output in combination with other methods will allow you to convert export procedures no matter how complex the procedures are.

Data-Entry Forms

Building Data-Entry forms (DEF) is the simplest job. A DEF that is an optional element of a procedure is built in the same way as any view form used to display table data. It is recommended that you use the same styles as when designing a view form (for example, the fields of the Required type used on Data-Entry form and view form should look the same).

• Each DEF should have two special purpose buttons: Run (with the Record Save As New action) and Close (with the Document Close action). Such buttons are used to replace the “Press F2 to print or Esc to exit” string and maintain the Windows “point-and-click” functionality.

Building Menus

By this moment your DFW application is almost finished, the only entity left to be converted is Menus. The aim of converting DFD menus is to preserve functionality but create attractive menus by utilizing a wide range of the DFW resources (i.e., styles): menu choices can be represented as buttons, you can use graphic elements to enhance the document appearance, etc.

• You could consider using a form instead of the menu entity since it offers more flexibility and does what a menu does, but also, opening parameters can be set (with the use of setting array variables).

All menus are built in DFW from scratch since they are not automatically transferred from DFD. The DFD menu structure is reproduced in DFW, with each menu assigned the same security level and each menu choice assigned the same action as in DFD. Any conversion implies that new DFW applications will have similar to DFD layout of elements. Given that DFD menus have standard DOS-like appearance, DFW menus are designed as view forms containing the same list of choices as in DFD.

• In DFW it is also possible to create custom menus (use Document >> Custom Menu) that will look like the DFW system menu: a horizontal menu bar with drop-down lists displayed at the top of the main application window. You might revise this menu bar and delete unnecessary system menu items or add new items of your choice.

Not all the menus should be converted one-to-one. DataEase has menus of the chain type, called Chain Menus that might be encountered in DFD applications. A chain menu is a special batch-processing menu with choices whose actions may be various commands (run a procedure/control procedure, open form, system commands, etc.). After a sequence of actions is processed, DataEase returns control into the invocation point.

• It is recommended to replace each DFD chain menu with a DFW control procedure because procedures offer more flexibility. An invocation point of a control procedure that replaces the appropriate DFD chain menu can be either a start-up document or a menu choice.

Users & Security Levels

Users is one of the entities that automatically migrates to DFW and is available from the very beginning of the conversion process. A user who has access to a database is identified by a user name and password. Each user account as well as security level and a start-up document that appears upon logging on are specified in the Users file. A start-up document can be a menu with a list of choices to select from, a procedure (new in DFW!) or the DFW system menu. Since a menu can be a start-up document, you need to check the Usersproperties and edit those menu names that have been renamed in DFW.

Conclusion

It is impossible to cover in one article the conversion theme in full and we hope to continue the discussion and provide more details in the next “Dialogue” magazine issues. In this article we have tried to summarize the conversion technology and demonstrate the conversion common approaches and best practices: this article should not be considered a complete guideline to conversion but rather an overview of conversion best practices.

• It should be mentioned that some of the conversion jobs could be automated by creating relatively simple tools or using third-party utilities.