Working with DataFlex 2021

Working with DataFlex 2021 is a straightforward process once you have a basic understanding of how it differs from prior releases of the product. Our advice is to go step-by-step as you gain more familiarity with DataFlex 2021.

Step 1 – Install DataFlex 2021

Just as with all previous releases, you can safely install DataFlex 2021 side-by-side on a machine with previous revisions of DataFlex. Since the Studio is mainly a 64-bit product it defaults to the Program Files folder instead of Program Files (x86).

DataFlex 2021 installs with an extendable, 60-day evaluation license, there is no need to install a registration code in order to start.

Please note that DataFlex 2021 uses the same revisions of the Codejock components (18.3.0) as DataFlex 19.1, so if the last action you take on a system is to uninstall either product, you will need to manually register those components for the remaining installation to function correctly. You can use the “RegisterCodejockControls” batch file in the Bin folder to do this (you need to run this batch file using “as Admin”).

Also note that if you are updating from a prior pre-release build, we recommend that you do so using the following procedure:

• Stop the DataFlex 2021 Web Application Server (using the Administrator)
• Uninstall the existing pre-release build
• Check to see if any files are left behind and remove if necessary
• Install DataFlex 2021

Step 2 – Read the Entire What's New Documentation

We know it’s not the most exciting part of experimenting with a new toy, but your experience with DataFlex 2021 will be more satisfying if you take the time to review the documentation completely.

Step 3 – Use the Studio

We’ll assume that you are already familiar with DataFlex 19.1 (if you are jumping into DataFlex 2021 from earlier revisions there will be more to get used to, depending on your usual working environment). Here are some areas to pay particular attention to:

• While the Studio itself is 64-bit, you can compile and debug both 64-bit and 32-bit applications. This is done on a project by project basis in a workspace and you can control this easily from the drop-down in the toolbar. You can also set the default for any project in the Compiler tab of Project Properties.

• When looking at the Project Properties, note that in addition to the current mode, there are optional suffixes for the compiled output. Our recommendation is to leave the 32-bit suffix blank and use “64” for the 64-bit suffix. Note that since web applications are always WebApp.exe, you must not set any suffix for either 32 or 64-bit.
• One aspect of working with DataFlex 2021 that is not readily apparent is that once DataFlex source is modified with the Studio it is now UTF-8 encoded instead of OEM. The Studio will automatically insert a Byte Order Mark (BOM) at the top of every source file it touches. The differences in encoding in all areas of the product are fundamental to understanding Unicode support in DataFlex 2021 and your applications, so make sure you review the sections on Unicode in DataFlex and Character Encoding.
• Developers that need to maintain backwards compatibility in their source and are not immediately using the Unicode capabilities of DataFlex 2021 can change the default treatment of DataFlex source files with a new “Save source files as OEM” option in the Studio (found under “Configure Studio | Editor”). When selected, the Studio will continue to save all source files as OEM unless it detects non-OEM characters in the file. It will then offer to convert that file to UTF-8 before saving so that there is no lossy data conversion. These are the rules of how all files are handled:
• DataFlex Source
• All default extensions plus any additional extensions added in the Studio configuration
• Default mode - all files are treated as UTF-8 and saved with BOM (we don’t add the BOM during migration, so until files are edited and saved they are still OEM on disk)
• Save as OEM mode - all files without a BOM are treated as OEM until the first Unicode character is used, then BOM is added and that file is UTF-8 from then on (any file that already has a BOM retains it and is treated as UTF-8)
• Other Files
• Files are assumed to be UTF-8 (prior releases assumed OEM) unless a UTF-16LE BOM is detected in which case the file will be read as UTF-16
• Files are always saved as UTF-8
• Files that already have a BOM will keep that BOM
• Files without a BOM will stay without a BOM

Step 3 – Experiment with the Examples

The main example workspaces all support compilation in both 64 and 32-bit. They also support Unicode but you need to convert the data to SQL Server to store Unicode data. While the examples are relatively simple (by design), they are a great way to play around with the Unicode features of DataFlex 2021 for that very reason; in just a few minutes you can experience what a fully Unicode application will feel like!

Here are some simple steps you can run through to experience all the new features of DataFlex 2021. They apply to any of the Order Entry - based examples (Web or Windows) but we’ll use the standard Order Entry Windows workspace in the following steps:

• Open the Order Entry workspace in the Studio
• You’ll notice that the project is set to compile for 64-bit and compiler warnings are enabled so you can see it compiles “cleanly”
• You can easily toggle back and forth between 64- and 32-bit and run and debug both from the 64-bit Studio
• Open the Customer view and translate any of the text to the language of your choice using Google Translate. We’ll use Macedonian (it’s an up and coming market) and change:
• Customer Entry View to Приказ на влез на клиент
• Customer Number: to Број на клиенти:
• Street Address: to 街道地址:  yes, this is traditional Chinese, just to show that we can use any language or mix of languages
• Make as many changes as you wish and compile and run
• Note that you can use any capability of the Studio to add Unicode text to your application; the code editor, object properties, wizards, etc.
• Compile and run (either 64- or 32-bit) and you’ll see…

• This application is currently using the embedded database, so what happens if t we try to use Unicode data? Find the “Access Miles” customer and translate the customer name to Chinese 訪問里程 and paste that into the entry form.
• At this point before DataFlex 2021, you would immediately see lossy data (???) as the controls converted the data to OEM. All user interface controls in DataFlex 2021 fully support Unicode data.
• If we save this record and re-find it, we’ll notice that our wonderful Chinese data has turned to ??? because saving to the embedded database is limited to OEM data.
• Our next step will be to convert our Order Entry database to use Microsoft SQL Server so we can use Unicode data. If you are not familiar with this process see the documentation on Data Connectivity, and in particular, Using Managed Connections and Converting Data.
• Create a Managed Connection and an Order Entry database
• Use the SQL Conversion Wizard to convert the table structures and data to SQL Server
• Notice that all of the DataFlex ASCII columns have been converted to nvarchar columns; these support Unicode data (where varchar would not).

• Compile and run and now you can use Unicode data throughout the application...

• The same basic steps can be used for a WebApp as well – play to your heart’s content!

Note that we have focused the documentation on using Microsoft SQL Server as our back-end test environment. DataFlex 2021 includes the drivers for IBM DB2, MySQL, PostgreSQL, MariaDB and Oracle, so you can also experiment with those back-ends. Be sure to setup your environment correctly:

• How to set up and test using Aurora
• How to set up and test using IBM DB2
• How to set up and test using MySQL
• How to set up and test using PostgreSQL
• How to set up and test using MariaDB
• How to set up and test using Oracle

Step 4 – Migrate Your Applications

Of course, the most interesting aspect of experimenting is to see what happens with your own applications as you migrate them into DataFlex 2021. There are many layers to this process and those will change depending on the combination of your starting point (the current host revision for any application) and your goal. Some things to consider before you begin this process…

• Make copies of your application and library workspaces for experimenting with migration. This is important because, as mentioned earlier, any source files the Studio touches will be converted to UTF-8 encoding. Also, for complex workspace structures it’s generally easier to “migrate in place” with workspace structures that have already been copied to new locations.
• For applications that use SQL Server, we strongly recommend that you make a copy of the database to use with the migrated applications. As you progress past the basic level of migration (see below) you may need to make changes to your database. For instance, you may need to update the database in order for it to support Unicode data.
• Those of you who have already updated your applications to DataFlex 19.1 and used the compiler warning system to clean up your code have a huge step up in the process of migrating to DataFlex 2021. If you have not gone through this process, we strongly recommend that you review “Language and Code Cleanup”, “How we cleaned up our own code” and “Compiler Warnings” sections of the documentation before proceeding.
• Migrating to DataFlex 2021 can be done to different stages to achieve various goals. The first stage of basic migration involves making only those changes absolutely necessary to compile and run under DataFlex 2021, resulting in an application that is still 32-bit and does not need or use any Unicode capabilities. While the ultimate goal for most developers will be full Unicode applications running in 64-bit, there are many reasons for focusing on basic migration first:
• You are starting with applications that still use the embedded database. The embedded database has always used OEM encoding and will continue to do so in DataFlex 2021.
• You are using 3rd party components that do not have 64-bit and/or Unicode capable versions, or you are simply not ready to take on upgrading to their components that are capable.
• One or more of your applications will not need 64-bit and/or Unicode capabilities, but you still want all the advantages of developing and deploying in the most up-to-date DataFlex environment.
• Once your application can compile and run at this basic stage of migration, you can begin the process of taking it to subsequent stages…
• Address Unicode-related compiler warnings
• Convert to full 64-bit
• Convert data to a Unicode-capable database (Microsoft SQL Server is a good candidate)

Here are some step-by-step examples of running an application though these stages. We’ll use our own DataBase Builder project (from 19.0 so that it hasn’t been “cleaned up” yet) in our references. What you see will depend on the applications you choose to experiment with.

• Make copies of your application and library workspaces for use with DataFlex 2021.
• Make sure that your copied structure is complete and any references to libraries are correctly using the copies
• If the application is already using an SQL back-end, create a copy of the databases it uses because you will likely be making changes on the backend
• Check to make sure that none of your SQL data still uses the OEM Table Character Format
• Make sure that your managed connection(s) are using the new databases
• This entire new structure and data should be compliable and usable in their host revision before continuing
• For DataBase Builder there are no libraries and no database, so this was a simple copy of the workspace
• Open the workspace in the DataFlex 2021 Studio and migrate all libraries and the application workspace “in place” (this is the easiest method for experimentation)
• The number of changes that are made during migration depends of the host revision.
• For applications already hosted in DataFlex 19.1, migration will simply change the revision in the .sws file and add a couple of new lines to the .cfg files of your applications
• At this point, you’ll notice that migrated projects are set to 32-bit and the compiler warning system is suppressed.
• Press compile!
• DataBase Builder reports over 300 errors
• If your application has not been previously migrated to DataFlex 19.1, some (perhaps most) of the errors you see will be due to the code cleanup done in that revision. Add the use statements for OldDFAllEnt.pkg and/or OldFMACCommands.pkg to check for those type of errors and recompile.
• DataBase Builder reports 8 errors
• We are not going to start the process of updating the application to resolve the errors (or, in subsequent steps, warnings) at this time. The goal is to get a good feel for what the complete process will entail.
• Use Project Properties to turn on Compiler Warnings by unchecking the “Suppress Compiler Warnings” option and press compile
• DataBase Builder reports over 4,000 warnings
• Don’t panic, it’ll be fine
• Since we’ve brought in the entire set of old classes with OldDFAllEnt.pkg, you will likely find that your application does not actually use them all and many of the warnings are just because the old packages did not go through the code cleanup process. You can copy OldDFAllEnt.pkg from the Pkg folder into your AppSrc folder and start pruning down the classes that get included to get rid of those you know are not used by your application.
• For DataBase Builder we commented out the following in our local copy of OldDFAllEnt.pkg

//Use WinQl32.pkg

//Use CrystalReport.pkg

//Use dafmac.pkg

• Database Builder reports just over 3,000 warnings
• You can continue to cycle through this culling process – the goal is to eliminate as much code that triggers unnecessary warnings or errors (note that you may find use statements or commands in your code that your application simply doesn’t use anymore)
• While the eventual goal is to clean up all the warnings, what we really want to know is how many of those warnings keep our application from being Unicode capable. We can easily find that out by adding the following to our application (just after the “Use DFAllEnt.pkg” statement for Windows applications or “Use AllWebAppClasses.pkg” statement for WebApps):

CompilerLevelWarning General Off

CompilerLevelWarning Unicode On

• DataBase Builder now reports 440 warnings (see, we told you it was gonna be fine)
• At this point you can start to get a feel for the types of things you’ll need to update for your application to be fully Unicode capable and 64-bit capable (from a DataFlex perspective – interfacing to external APIs and/or 3rd party components are subsequent stages of the migration process). Use the information in the rest of this document to help you understand the other necessary changes.
• If your application is still using the embedded database, the next step is to convert your data to Microsoft SQL Server. Though your data will be more complex than the examples, the steps are essentially the same as outlined above. If you are not familiar with this process see the documentation on Data Connectivity, and in particular, Using Managed Connections and Converting Data.
• Create a Managed Connection and database for your application
• Use the SQL Conversion Wizard to convert the table structures and data to SQL Server
• Notice that all of the DataFlex ASCII columns have been converted to nvarchar columns; these support Unicode data (where varchar would not).
• If your application already uses SQL Server, there are different steps to take:
• When you originally converted your data, did you select ANSI or OEM conversion? If OEM, you’ll need to update the tables to use ANSI data; see the OEM to ANSI Conversion Wizard section for details.
• Check the SQL data types used for the ASCII columns in your tables. Anywhere you want to use Unicode data you need to change the data type for that column to nchar or nvarchar. You can use any method you are comfortable with to make these changes. Since the data was previously limited to ASCII data, changing the data types to the Unicode capable data types will not result in lossy conversions of existing data. See "Making Existing SQL Databases Unicode-capable" for more information,
• Don’t feel like you need to convert all your columns at once, you can simply change a few to see how entering and sorting Unicode data feels

Obviously, the steps outlined are a very simplified view of application migration, and you’ll still have to deal with all your external interfaces – but from a high-level perspective it’s relatively straightforward:

• Determine which stage of migration you require for any particular project
• Understand the types of changes that may be necessary (reading this document completely will get you there)
• Use the Studio error and warning system to find as much of the code subject to change as possible
• Examine your use of external components and APIs and adjust them as required

Once you get into the process you’ll find that its all about repetition; yes, there may be hundreds, or even thousands of changes necessary – but it is really only a small handful of different types of changes that you repeat a number of times. The learning curve is all in how to handle each different type of change.

Step 5 – Use the Forums and Learning Center

There are specific forums for early testing, Windows, Web and Mobile, DataBase Connectivity, Reporting and much more. There are also many DataFlex Learning Center courses that will help you efficiently move to DataFlex 2021.

There are many developers working with DataFlex 2021 and getting involved in the forum discussions could save you hours or days of time. Conversely, sharing your own experiences could save other developers hours or days as well.

Step 6 – No Excuses

Come on, admit it, you didn’t really read all the documentation now did you? Trust us, it won’t take very long and you can relax with a refreshing beverage while doing so. Give it a shot; it certainly won’t hurt...

See Also

What's New in DataFlex 2021