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
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)
- 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,
- 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
- 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
- Compile and run and now you can use Unicode data throughout
- 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:
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
- 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
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
- Make sure that your managed connection(s) are using the new
- 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
- 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
- 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
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
- 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
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
- 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
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
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...
What's New in DataFlex 2021