Upgrading to DataFlex 3.2

A Data Access Corporation White Paper
by Dennis Piccioni

May 27, 1998
Last Edited: September 18, 2002

This paper should be read by anyone upgrading to DataFlex 3.2 from any prior revision. Although the main focus is on changes from revision 2.3 to 3.2, many of the issues discussed here apply to other revisions as well. Specific references to revisions other than 2.3 and 3.2 are made expressly wherever necessary.

This paper discusses numerous issues commonly encountered when upgrading:

Why Upgrade?

There are many valid reasons to upgrade to DataFlex 3.2, the most current revision of character-mode DataFlex. Here are just a few of them:

While DataFlex was released prior to Windows ME and XP and thus is not fully tested and supported on those platforms, we have received no reports of unusual problems on those platforms.

The DataFlex 3.2/Visual DataFlex filelist has been extended from 255 to 4095 data files, eliminating the need for use of multiple filelists for large projects.

Note: Be careful when mixing data files used with extended filelists in older environments that do not support the extended filelist. Data files that relate to other data files that have file numbers above 255 are changed to file version 4, which cannot be used by older DataFlex revisions.

Prior to DataFlex 3.1, all online indexes were updated during every save. Now, only the affected indexes (e.g. those indexes that had a segment value changed) are updated.

A second index optimization affects record finding. If a data file is searched using an index, the complete record buffer is not pulled into memory unless a field that does not appear in the search index is referenced.

In older DataFlex revisions, when a lock was issued, all open data files were locked. When using object-oriented code with Data_Sets or DataDictionaries in DataFlex 3.2 or VDF, only the files in the current Data_Set or DataDictionary structure are locked.

In DataFlex 3.2 and Visual DataFlex, changes that previously could only be made in the DataFlex utilities, for example DFFile, can now be made in a DataFlex program using API commands. Now you can simply send your customers a disk or email with a DataFlex program that will upgrade their file definition, as opposed to going to the customer site, or sending a consultant, to run DFFile to update the customer's data files.

Read more about updating data file definitions in Data Access Nederland's white paper Data Definition in Visual DataFlex. Most of the code in this paper, with the exception of user interface code, can be used in DataFlex 3.2.

You can also find information about this topic in the 3.2 and VDF help under:

These new field types were added in DataFlex revision 3.0.

Running on Linux and Unix

There are a few differences between the Dos/Windows and Linux and Unix platforms.

The path separator in Linux and Unix is “/” (slash or forward slash), not “\” (backslash), as in DOS/Windows. In most cases, this paper will use "\" to display DataFlex paths (e.g. "c:\df32\usr"). Please substitute forward slashes as needed.

If you are writing applications for DOS/Windows and Linux/Unix platforms, you should use the Sysconf function with the Sysconf_Dir_Separator to obtain the path separator in your program code:

String sDirSeparator
move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

The default install location for DataFlex 3.2 on DOS/Windows is c:\df32.
The default install location for DataFlex 3.2 on Linux/Unix is /usr/local/df32.

Where batch files are used in DOS/Windows environments, shell scripts are used in Linux/Unix.

DataFlex source code files in Linux/Unix must have all lowercase names.

On the new DataFlex 3.2 for Linux CD (part # 555260cd), we have provided 2 shell scripts to aid you in converting your existing files to lowercase names: lcase and lcaser. The lcase script lowercases all files in a single directory and the lcaser script lowercases all files in a directory and all subdirectories of that directory. To execute either script, simply type the script name, with no arguments, in a terminal changed to the directory you wish to affect:

cd /usr/local/df32/mysourcecode
lcase

DOS/Windows and Linux DataFlex files (data files and programs) created on any Intel x86 platform are binary-compatible, which means that they can be compiled on one platform and run on the other. If you transfer files between platforms using FTP, just transfer binary files using binary mode in FTP.

Converting Data Files to the Current Revision

DataFlex 3.2 (and Visual DataFlex) can read from and write to DataFlex data files from revisions as old as 2.3. You do not have to upgrade data files if your file revision of your data files is at least 2.3. However, you can gain new functionality and data integrity by doing so.

Here is a complete breakdown of what needs to be done and what can be done with data files from various DataFlex revisions.

DataFlex 3.2, 3.1 and Visual DataFlex share a common database engine (when using DataFlex data files). Therefore, data files created in these revisions are 100% compatible with each other.

If you are converting from DataFlex revisions prior to 2.3b, you must use revision 2.3b as a go-between.  DataFlex 2.3b came with a utility called dfconver.exe. Executing this utility will automatically convert all data files to 2.3b format.

You can download the DFConver utility from the DAC FTP Site separately from DataFlex 2.3b. Detailed instructions are provided in the downloaded file.

DFConver utility, Location: ftp://ftp.dataaccess.com/pub/products/dataflex/tools.

Data files from these revisions cannot be converted using any utility. These files need to be exported to ASCII (plain text) files and read back into a current (2.3b or greater) data file.

Note: Whenever a data file format is upgraded to a higher revision, the prior revision can no longer read the changed data files. This rule applies to changes for these revisions:

Note: DataFlex revisions 3.0 - 3.05 can access 3.2/VDF data files, but this should not be done if those files are using Novell Netware's Transaction Tracking (TTS) in DataFlex 3.2/VDF.

If you do want to convert all your data files to 3.2 format, you can do so using the DFMaint utility:

  1. Go to a command prompt.
  2. Run \df32\usr\setpath.bat or other batch process to set your environment for DataFlex 3.2.
  3. Run DFMaint.exe.
  4. Select "Filelist" from the "Maintenance" menu.
  5. Highlight the file to convert.
    => To select all files, choose "Select All" from the "Filelist" menu.
  6. Choose "Convert" from the "Database" menu.
  7. You will be prompted whether to use a temporary file or convert in place. We recommend the default, "Use temp file".

Converting Program Files to the Current Revision

Invalid Characters in Data File Field Names and Data File Rootnames

There are a few conventions that were commonly used by DataFlex 2.3 developers that may present problems in DataFlex 3.2. One of these conventions was the use of an "@" character and other undocumented characters in front of the data file rootname in filelist entries and/or the use of such characters in front of data file field names.

This was never supported and will no longer work, because DataFlex now has the ability to use other database drivers, make API calls and other such options, which cannot support such characters at the runtime and driver levels. Even the DataFlex 2.3 User's Guide documented that the only characters allowed for field names are letters, numbers, underscore ("_") or the pound sign ("#"), and the field name must start with a letter.

Filelist Entries

In order to remove the invalid characters from filelist entries, you can run the DataFlex File Maintenance Utility (dfmaint).

1. From the Maintenance pulldown menu, select Filelist to display the current filelist entries.

2. Select the filelist entry you wish to edit and press <Enter>.

Common symptoms experienced are the inability to open the menu.dat file in the menu program. In this case, you want to select filelist entry number 49, the DataFlex Menu File.

3. Make sure that the rootname does not contain any illegal characters such as "@" or ":", such as a commonly used rootname entry in DataFlex 2.3b: "@:menu".

Data File Field Names

In order to remove invalid characters from File.Field definitions, you need to open the file using DFFile, the DataFlex File Definition Utility. Some commands, make_file for example, will not work properly with invalid characters in front of file.field names.

Note: You can still use the "@" character in front of a data file's User Display Name to hide that data file from the user in DFQuery.

Upgrading Source Code to DataFlex 3.2

Properly written source code from prior revisions of DataFlex is fully compatible with revision 3.2 and should compile and operate without problem. The DataFlex 2.3 compiler and runtime were not as strict as the newer versions. In some cases, improper code was allowed to compile and/or run under DataFlex 2.3b, but will generate compiler or runtime errors when used with a newer revision of DataFlex. Data Access Corporation cannot warrant the validity of source code written by someone outside of DAC in every case.

Troubleshooting DataFlex 3.2

The DFPATH Environment Variable

This is the most important environment variable from a DataFlex viewpoint. DataFlex uses this variable to find everything it needs:

If there are multiple copies of any of the above files along the directories listed in DFPATH, DataFlex will use the first copy that it finds.

The DFENV Environment Variable

The DFENV environment variable was added in DataFlex 3.2 to work around DOS and Windows operating system limitations, such as command line length and environment space.

DFENV points to a file called dfenv.cfg. The variables set in this file will override any variables of the same name in your environment. If dfenv.cfg contains a  DFPATH environment variable, and your current environment also has DFPATH set, the one in DFENV will be used (provided the DFENV environment variable is set). To see your current environment variables, type "set" and press <Enter> at the command prompt.

Other Environment Variables

HOME is an environment variable set in many networking environments, and it may interfere with DataFlex 3.2 running properly if it points to a directory containing another version of DataFlex or parts thereof (watch for files like termlist.cfg and *.dfr - frequent culprits). Specifically, the DataFlex runtime looks for a copy of termlist.cfg first in the directory specified by HOME. Perhaps the best method to avoid problems with HOME is to never store a termlist.cfg file in the directory HOME points to.

DFPROG is an older environment variable used in versions of DataFlex prior to 3.2. You can ignore it or eliminate it from your DataFlex 3.2 environment.

PATH is the environment variable that the operating system uses to find executable files (programs) such as; dfrun.exe, dfcomp.exe, etc.. The directory where the DataFlex executables are located must be part of the PATH environment variable. In the case of DataFlex 2.3b, that directory is c:\df23 and for DataFlex 3.2 that directory is c:\df32\bin (/usr/local/df32/bin on Linux/Unix).

If you experience problems running DataFlex 3.2; just to play it safe, eliminate any additional environment variables until you get DataFlex running. If those environment variables are needed for other applications, you can add them back, once you get DataFlex running properly.

Setting up Batch Files

Here are some batch file examples for easy switching between versions of DataFlex. These batch files will run only on DOS-based operating systems or in DOS sessions under Windows.

Many programmers, as well as end users, run multiple versions of DataFlex and use batch files to switch from version to version. Here at DAC we are always switching among versions: 3.1d, 3.2, Visual DataFlex 8.1, Visual DataFlex 8.2, etc..

Following are some batch file examples for switching among versions. You’ll want to place these batch files in a directory that is included in your  PATH environment variable (e.g. use a directory c:\batch to be included in your  PATH, to contain all batch files).

Set32.bat

Use this file to set up your environment for running DataFlex 3.2 and switch to your application directory:

@echo off
echo Setting Up DataFlex 3.2 Environment
set DFENV=c:\df32\usr\dfenv.cfg
set DFPATH=     REM blank DFPATH env. variable
set DFPROG=     REM blank DFPROG env. variable
echo Switching to DataFlex 3.2 Application Area
c:
cd \app\src

Set23.bat

Use this file to set up your environment for running DataFlex 2.3 and switch to your DataFlex 2.3b directory:

@echo off
echo Setting Up DataFlex 2.3 Environment
set DFENV=     REM blank DFENV env. variable
set DFPATH=.;     REM current directory only directory in DFPATH
set DFPROG=.;
echo Switching to DataFlex 2.3b Area
c:
cd \df23

Note: The DFPROG environment variable is used by DataFlex revisions 2.3 and 3.01 to find the location of its executable files (i.e. dfrun.exe).

Note: Writing batch files and using environment variables are advanced operating system topics. If you want to learn more about these topics, you can consult your operating system manuals or the maker of your operating system. You can also go to your local bookstore and find hundreds of books on using operating systems like DOS, Unix and Windows and creating batch processes for these systems. These topics are NOT supported by Data Access Corporation.

Creating Shortcuts for Running DataFlex on Windows

Under Windows, you usually want to provide a simple shortcut that your end users can click on to start their DataFlex application.

The trick here is to make the shortcut not to the setpath batch file or dfrun.exe, but to command.com. Command.com is the executable program that executes a DOS session under Windows.

An Example Shortcut on Windows 95/98/ME

Starts the session in the specified directory.

This executes the batch file immediately after starting the DOS session and sets up the session's environment to run DataFlex.

An Example Shortcut on Windows NT/2000/XP

Starting a DataFlex Application From a Windows Shortcut

You can edit the batch file that is executed when launching an application to have "dfrun" or "dfrun ApplicationName" as the last line in the batch file. This would then launch the DataFlex menu or any desired DataFlex application in that DOS session.

Using An Existing 2.3b Menu

There are 2 pieces to the character-mode DataFlex menu system:

1. The Menu Data File (menu.dat)

This data file contains the entries that make up the menu. It can be edited using the DataFlex Menu Maintenance Utility ("dfrun menudef"). To retain the menu items you had in your 2.3b program, simply copy over the existing menu.dat file.

2. The Menu Program (menu.flx)

Note: Do not compile and/or run the 2.3b menu.src in DataFlex 3.2. This will not work, which is why menuold.src was provided with DataFlex 3.2.

Note: DataFlex 2.3b came with flex.exe, which was a "loader" program. It called dfrun, and if dfrun ever closed, it called dfrun again. This functionality is not available in a 32-bit DOS program, thus flex.exe is no longer available.

Accelerator Keys (FlexKeys)

DataFlex 3.2 uses CUA compliant accelerator keys, such as F2 to Save, F8 for "find gt", Shift+F2 to delete, etc.. These keys are quite different from their 2.x predecessors, but it is useful for your end users to learn these keys, because many other applications share the same accelerator keys, making it easier to remember them in the long run. Nevertheless, in the short term, your end user may want to continue using the accelerator keys that they are used to.

For this purpose, we have provided a file that contains the accelerator key definitions as they were in DataFlex 2.3b (\df32\usr\df23ini.cfg) and a second file with the DataFlex 3.2 accelerator key definitions (\df32\usr\df32ini.cfg). You can add a line of code to any DataFlex 3.2 program to read either of these files:

read_dfini "df23ini.cfg" - program starts using definitions from DataFlex 2.3b
read_dfini "df32ini.cfg" - program starts using definitions from DataFlex 3.2

Note: If a program uses a dfini.cfg file and chains to another program, the second program will also use the settings defined in that dfini.cfg file.

By default, the DataFlex 3.2 runtime does not use a dfini.cfg file, all the defaults are hardcoded into the runtime. However, if the runtime encounters a file called dfini.cfg along dfpath, or if a read_dfini statement is in a DataFlex program, it will use the definitions in that file.

Do's and Don'ts of Running DataFlex 3.2 and Prior Revisions Concurrently

You MUST keep the same date format in all versions of DataFlex that share the same data files! Either use 2 digit years or 4 digit years throughout, do not mix them. You should use 4 digit years rather than 2 digit years, otherwise your applications will have problems the first time a date of 01/01/2000 or later is used.

Specifically, if you use the Y2K-Enhanced capabilities of DataFlex 3.2 or Visual DataFlex, and turn on the Date4_State, dates are automatically saved with 4 digit years. After this, you cannot share this data with versions of DataFlex using dates with 2-digit years.

You can only use Novell's Transaction Tracking (TTS) with DataFlex 3.2 or Visual DataFlex. If you do use TTS with these revisions of DataFlex, you cannot share those data files with revisions of DataFlex that do not support TTS, or you will irreparably damage your data files.

If you make changes to your data file definitions (e.g. add a field) in DataFlex 3.2 or Visual DataFlex, DataFlex 2.3b will no longer be able to access these data files.

Note: You can query the version of a DataFlex data file in a DataFlex program by using the "DF_File_Revision" attribute.

EXAMPLE:

integer iRev
Open CUSTOMER
get_Attribute DF_File_Revision of CUSTOMER.File_Number ;
    to iRev
showln "File Revision of Customer File: " iRev "."

Expression Evaluation

There have been some changes in the way logical expressions are evaluated in DataFlex revisions 3.2:

Once again, let's look at an example to illustrate the differences. Consider the following lines of DataFlex code, and look at the results they will produce in DataFlex 2.3 and DataFlex 3.2:

string A
string B
move "3" to A
move "2" to B

 

Result
Expression DataFlex 2.3b DataFlex 3.2
showln (A + B) 5 "32"
showln (A * B) 6 "3 2"
showln (A - B) 1 "32"

In DataFlex 2.3, addition of 2 string variables would result in the mathematical addition of the values in the 2 variables; in DataFlex 3.2, the 2 strings are concatenated instead.

Compiler Errors

For example, the "Check=" entry option allowed checking for ascii characters without enclosing them in quotes. The DataFlex 3.2 compiler creates an error in this case.

Incorrect syntax (but not caught by 2.3 compiler):
     Accept FILE.FIELD {Check=1|2|3}

Correct syntax:
     Accept FILE.FIELD {Check="1|2|3"}

The -x23 Compiler Flag

For backward compatibility purposes, DAC provided the compiler flag -x23 (i.e. "dfcomp source.src -x23") for compiling programs as if they had been compiled in 2.3b. This flag was provided until revision 3.04 to allow time for developers to bring their existing programs up to date. Most of the changes in DataFlex that are outlined in this paper and affect existing 2.3 DataFlex code were made to DataFlex with revision 3.0, in about 1990. At some point, a choice must be made between backward compatibility and progress, and as of revision 3.05, the -x23 flag is no longer supported, so you must make the appropriate source code changes to existing DataFlex 2.3 programs.

Runtime Errors

DataFlex 3.2 and Visual DataFlex are much stricter about enforcing proper rules, for multiuser coding, database design and many other areas than prior revisions of DataFlex.

This particular runtime error points out errors in multiuser coding logic. The rules for correcting these coding errors are simple and straightforward:

Proper Multiuser Coding Examples:

clear NEWFILE
lock
    move VAR to NEWFILE.FIELD
    saverecord NEWFILE
unlock

Note: In many instances a reread command instead of a lock command will work with a new record. In this case, you MUST use the reread command without any files listed as parameters. If you try to reread a specific file (e.g. reread CUSTOMER) which does not have an active record, you will get an error "status <<25>> record not found". There is a slight penalty (time) for using the reread command without any parameters, which is that all open files with an active record that are not flagged read-only will be reread.

reread FILE
    move VAR to FILE.FIELD
    saverecord FILE
unlock

reread FILE
    move FILE.FIELD to NEWFILE.FIELD
    saverecord NEWFILE
unlock

* Explanation of terms:

Note: There are important differences between the saverecord and save commands. The difference is that the save command attaches related ancestral file (parent, grandparent, etc) information, so that information from the related parent record will overwrite information moved manually into the child record buffer when saving. Saverecord does not do anything at all with related files, it only affects the file(s) listed as parameter(s).

You can find additional information on multiuser coding in the white paper Transactions in DataFlex 3.1.

We have received some reports of encountering this error from developers upgrading to DataFlex 3.2 or Visual DataFlex. This error will occur at runtime whenever a relationship is found between 2 database fields that are not of exactly the same type and length. Overlap fields are the only exception to this rule; they may relate to either other overlap fields or ASCII fields of the same length.

Note: Many developers using 2.3b used record number relationships, where a field in one database file is related to the RECNUM field in another file. When upgrading to 3.2, suddenly this message appears. This is usually because the "relating from" field was defined as Numeric 6.0, instead of Numeric 8.0, which is the type and length of the RECNUM field.

If you are using Data_Sets or DataDictionaries in your programs, you must set the affected data files' transaction type to either Client Atomic or Server Atomic, you cannot leave it as None.

Older revisions of DataFlex allowed execution of the zerofile command while other users had access to the data file. This is no longer the case. For data integrity reasons, starting with DataFlex 3.2, a data file must be opened exclusively to zerofile it. Otherwise, the error message status 4177 "File access violation, file may be in use filename"  will be triggered.

If you are using a modified DataFlex runtime, check with the provider of that runtime in regards to any of the issues discussed in this paper.

Graphics Commands

Graphics commands for character-mode DataFlex are no longer supported in any revision newer than 3.01b, so any such commands will have to be removed from the source code of your program(s).

DataFlex 3.2 Utilities

All of the following utilities are documented in the DataFlex 3.2 User's Guide.

DFAdmin

DFAdmin is a superset of various other utilities, including, most notably, DFMaint and DFSort. Here are some of its features:

DFConfig

The DFConfig utility now provides much of the functionality provided by DFSetup in DataFlex 2.X, and some new features as well.

Some of the features of DFConfig are:

DFMaint

One of the best new features for developers in DataFlex 3.2 is in the DFMaint utility: The ability to edit the filelist entries! Here you can add, remove, and edit individual entries in your current filelist.cfg.

NOTE: The DFAdmin utility allows editing of multiple filelists, not just the current one (as DFMaint does).

The DataFlex maintenance utility provides access to the following:

DFQuery

In DataFlex 3.2, the DFQuery utility has been replaced with DFQ, a DataFlex program with the same functionality as DFQuery. Since DFQ is a DataFlex program, it can load database drivers using any available Connectivity Kit for DataFlex.

DFSetup

As of DataFlex revision 3.0, the DFSetup utility only validates and registers serial number, registration name and registration code into the binary file termlist.cfg. All other functionality DFSetup had in DataFlex 2.X has been moved to the DFConfig utility.

DFSort - Index Utility

In DataFlex 3.2, dfsort.exe was introduced as a new utility for reindexing. Dfindex was dropped from the product entirely starting with revision 3.1.

As an alternative, the DFAdmin utility can be used for reindexing. This utility even accepts command line parameters for all index manipulation.

Year 2000 Issues

Now a brief discussion of Year 2000 issues. You can find additional information on this issue in the following:

DataFlex has always been Y2K (Year 2000) capable, meaning that developers have always been able to write Y2K-compliant applications. In prior revisions, such as 2.3b, it was usually up to the developer to ensure data was displayed and saved with 4-digit years, but DataFlex already had the capability to store dates with 4-digit years. This meant creating on-screen and report date images with enough room for 4-digit years, and adding 693975 (the integer equivalent of 01/01/1900) to a 2-digit year, wherever dates were used.

In newer revisions of DataFlex (Visual DataFlex, DataFlex 3.2), we have provided an easier method, both for creating new applications that are Y2K compliant and for updating existing, noncompliant applications to full Y2K compliance.

DataFlex has always had the capability to store dates with 4-digit years, so a properly written DataFlex application in any version of DataFlex will be Year-2000 (Y2K) compliant. However, in DataFlex 3.2 (caution: revisions of DataFlex prior to 3.1c do not have the Y2K-Enhancements), we have implemented additional support for easily making your applications Y2K compliant.

There are numerous additional enhancements and bug fixes to DataFlex 3.2. Please consult the DataFlex 3.2 Readme file for more details on these enhancements and fixes.

Y2K-Enhanced Features

There are common methods used in all of these Y2K-Enhanced revisions:

This is a value between 0 and 99 which determines a "cutoff year", which determines at which year 2-digit entered year becomes a 19XX year or a 20XX year.

For example, if the Epoch_Value is set to 30 (the default):

When turned on, the runtime returns a date with a 4-digit year wherever the sysdate command is used.

When turned on, this state ensures that whenever a date is displayed or stored, it is automatically converted to a date with a 4-digit year.

For example: "09/17/2002" is displayed as "09/17/02"

This is a DataFlex program that changes all dates in existing data files from 2-digit year dates to 4-digit year dates. This utility does not change the format of any date fields or data files containing date fields, it only changes the content (value) of the date field. The utility can loop through all files on the current filelist or allow you to select a file to convert. Conv2000 is written in DataFlex and all source code for it is provided.

Implementation of Y2K-Enhanced Features

In DataFlex 3.2, DAC has provided a file called y2k.pkg, which contains the set_Date_Attribute command and default settings for Date4_State (dfTrue), SysDate4_State (dfTrue) and Epoch_Value (30).

To make an existing DataFlex 2.3b program Y2K enhanced, simply add this line to the beginning of your program and recompile the program under DataFlex 3.2:

Use y2k.pkg

TIP: In DataFlex 2.3b, all images had to be at the very top of the program. In DataFlex 3.2, this is no longer necessary, so you can place code in between images and even before any images at the top of the program. If you have a lot of programs (source files) to which you need to add the "Use y2k.pkg" statement, you could write a small DataFlex program to do this for you. See the DAW Technical Knowledge Base for more information.

A Brief Overview of Y2K.pkg

There are only 3 lines of code in y2k.pkg, which turn on all the automatic Year-2000 enhancements in DataFlex. Here is a brief look at each of the 3 lines of code in y2k.pkg:

Set_Date_Attribute Sysdate4_State to DFTrue

This line of code toggles the runtime to execute sysdate4 instead of sysdate wherever sysdate is used in a program. This returns the computer's system date with a 4-digit year.

Set_Date_Attribute Date4_State to DFTrue

This line toggles the runtime to automatically convert dates to 4-digit years whenever a date is moved to a data variable or a date field.

Set_Date_Attribute Epoch_Value to 30

This line of code tells the runtime the cutoff year that determines whether a date is converted to a 19XX year or a 20XX year during automatic conversion.

If you want to use a different cutoff year (Epoch value) from the default of 30, you can change the value here, then recompile all programs that contain "Use y2k.pkg". If you want a specific project to have a different cutoff year, you can copy y2k.pkg to the source code area for that project, then edit the Epoch_Value in that copy of y2k.pkg and recompile all programs containing "Use Y2K.pkg" for that project.

Separating Applications and Runtimes

DataFlex 2.3 was designed in simpler days of computing. Hard disks were smaller, less memory was available and applications were generally smaller and did fewer things. Developers usually had relatively few development tools (and revisions thereof) installed on their PCs. Those times have changed. Today, it seems one can never have enough hard disk space or RAM and most applications do a gazillion things, whether they are needed or not.

For programmers things have changed as well. It is common for application designers to develop with many different tools, even for a single application. We often have multiple versions of the same tools installed, if not for development, then to support customers who use these different tools and versions.

In DataFlex 2.3b, many developers kept the runtime files in the same directory as the application files (i.e. data and .flx files). In order to successfully upgrade to DataFlex 3.2, or to run the two (or more) versions of DataFlex simultaneously, these files need to be separated. Runtime files from the two versions will interfere with each other.

The Separation Process (a Step-by-Step Outline)

  1. The following steps will show you how to: Divide the source code and data files from your existing installation into separate areas. This makes maintenance easier and gets you ready to easily upgrade to DataFlex 3.2, as well as Visual DataFlex.
  2. Keep one copy of the source code in the 2.3b area and another copy in the 3.2 area.
  3. This allows you to edit either version of the source code without affecting the other.
  4. Create a shared data directory.
  5. You can access your data files using programs compiled under DataFlex 2.3b and DataFlex 3.2 at the same time. (This works for other revisions, such as 3.1, as well.)
  6. How to run DataFlex 3.2 and other (prior) revisions concurrently.
  7. You can keep existing programs running in an older revision of DataFlex until you have all components working in DataFlex 3.2.

1. Create separate directories for the runtime files and application files, and separate data and source code in the process.

For the remainder of this paper we will assume that the directory where your 2.3b license resides is c:\df23 – you can substitute your actual installed directory name and drive letter for c:\df23.

c:\df23 - original 2.3b directory
               - 2.3 runtime files will remain here
               - a copy of the source code files will remain here to be used with 2.3

c:\app - directory for your application files
                \data - data files to be shared between revisions 2.3 and 3.2 (subdirectory of \app)
                \src - source code files to be used with 3.2 (subdirectory of \app)

Separating your existing 2.3b directory this way will give you numerous operating options:

  1. Concurrently run DataFlex 2.3b and 3.2 (or just 3.2)
  2. Have an existing directory structure to easily upgrade to Visual DataFlex

A. Files to be moved into c:\app\data directory:

B. Files to be copied into c:\app\src directory:

One copy of the source code can remain in \df23 for use with (and to keep up) currently running 2.3b applications, and one copy will go into this directory for use with the new 3.2 version.

C. Files to remain in c:\df23 (runtime) directory:

2. Install 3.2 into a separate directory and install your DataFlex 3.2 registration code

For the remainder of this paper we will assume that the directory where your 3.2 license resides is c:\df32 – you can substitute your actual installed directory name and drive letter for c:\df32.

Note:

3. Concurrently Running DataFlex 2.3b and 3.2

A. Running DataFlex 3.2

1. Edit the c:\df32\usr\dfenv.cfg file:

Change the DFPATH= statement to include the c:\app\data directory

Before:

dfpath=.;c:\df32\usr;c:\df32\usr\help;c:\df32\lib;c:\df32\bin;
c:\df32\src\pkg;c:\df32\usr\examples\expense;
c:\df32\usr\examples\dar;c:\df32\usr\examples\ordentry;
c:\df32\usr\examples\big;c:\df32\usr\examples\report;
c:\df32\usr\examples\data;

After:

dfpath=.;c:\app\data;c:\df32\usr;c:\df32\usr\help;c:\df32\lib;
c:\df32\bin;c:\df32\src\pkg;c:\df32\usr\examples\expense;
c:\df32\usr\examples\dar;c:\df32\usr\examples\ordentry;
c:\df32\usr\examples\big;c:\df32\usr\examples\report;
c:\df32\usr\examples\data;

Note: the DFPath statements above may appear different depending on the software you use to view or print this document, but each DFPath statement is a single continuous statement.

2. Switch to c:\app\src directory
3. Execute c:\df32\usr\setpath.bat
4. Run DataFlex (dfrun programname, dfcomp, dfquery, etc.)

Note: You may want to use different dfenv.cfg files for different applications so that you can place numerous application specific environment variables into each file.

B. Running DataFlex 2.3b

  1. Switch to c:\df23 directory
  2. Set the DFPATH environment variable:
    set DFPATH=.;c:\app\data
  3. Make sure c:\df23 is in your PATH environment variable
  4. Run DataFlex (dfrun ProgramName, dfcomp, dfquery, etc.)

Moving On to Visual DataFlex

Now that Windows is the world's most prevalent operating system, the next step for many DataFlex programmers is moving on to Windows programming. When DataFlex 2.3 was released in 1987, the auto-design facility was so easy to use to create database applications that it was years ahead of the competition. With Visual DataFlex you can experience that feeling again in Windows. Visual DataFlex is a great environment for designing Windows applications and allows you to utilize your existing DataFlex knowledge.

Data files can be shared among DataFlex 2.3b, 3.2 and Visual DataFlex, so your customers can continue to run their existing character-mode applications while you incrementally upgrade them to Visual DataFlex. User interface components, such as data entry screens (views) must be redesigned in VDF using Windows GUI object classes. The Visual DataFlex tools, such as the Integrated Development Environment (IDE) and Database Builder, make writing Windows applications quite enjoyable.

Some parts of your character-mode DataFlex (2.3b or 3.2) source code can be reused (i.e. non-interfaced batch processes such as reports). You will be able to simply cut and paste many parts of your existing programming logic into your VDF applications.

Visual DataFlex, as well as the DataFlex 3.2 console-mode runtime, has the ability to load Windows drivers, such as the Pervasive.SQL Connectivity Kit (which provides an easy yet powerful client-server solution), ODBC drivers and native drivers for other databases such as DB2 and Oracle. You'll never again have to turn down a project because a prospective client is using DB2 and you do not have time to learn a new programming environment.

For more information on upgrading to Visual DataFlex, see John Tuohy's white paper Migrating to Windows with Visual DataFlex.

Appendix A: Directory Listing of a DataFlex 2.3b Development License

These are the files that are installed with a Full DataFlex 2.3b Development License, including all examples. When trying to resolve which files should remain in the 2.3b runtime area (c:\df23), you may use this as a reference for those decisions. These files should not be copied to your source code directory.

Keep in mind that your application may use files with the same name, so having them listed here does not guarantee that they are not part of the application. The sample files, as you see below, contain data files such as customer.dat and vendor.dat. If your application has data files with the same name, those files need to be moved to the data directory (c:\app\data). Your developer is the person who should provide you with that information.

cleanup.flx cleanup.src customer.dat customer.fd
customer.flx customer.frm customer.k1 customer.tag
custrpt.flx custrpt.rpt date.flx date.frm
dbread.flx dbread.src delqry.flx delqry.src
dfask.com dfauto.exe dfcomp.exe dfconver.exe
dfedit.exe dffile.exe dfindex.exe dfpack.exe
dfquery.exe dfrun.exe dfsetup.exe filelist.cfg
flex.exe flex.cfl flexerrs.flx flexerrs.dat
flexerrs.fd flexerrs.frm flexerrs.tag fmac
halo3270.dev haloact2.prn haloamde.dev halocljt.prn
haloclsr.prn halocm25.dev halocolm.prn halocono.dev
halocrna.prn halodblo.prn halodeba.dev haloepjx.prn
haloepsn.prn halogeni.dev halogncm.prn haloherc.dev
haloibm.dev haloibme.dev haloibmg.dev haloicba.dev
haloimgt.dev haloimwr.prn haloinda.dev halojlsr.prn
halolasr.prn haloljtp.prn halomits.prn halomult.dev
halonine.dev halopal.prn halopalm.dev halopcjr.dev
haloprsm.prn haloqdcl.dev haloquad.dev haloquad.prn
haloscio.dev halosigm.dev halostb.dev halotecm.dev
halotex.dev halotjet.prn halotosh.prn halovdaa.dev
halowyse.dev invoice.flx invoice.frm invt.dat
invt.fd invt.flx invt.frm invt.k1
invt.k2 invt.k3 invt.tag items.dat
items.fd items.k1 items.k2 items.tag
menu.flx menu.dat menu.tag menu.fd
menu.src menudef.flx menudef.src modmenu.flx
movement.flx movement.rpt pn90230.23b pn90250.23b
query.dat query.tag query.fd query.k1
query.hlp read.flx read.src sysfile.dat
sysfile.fd sysfile.tag termlist.cfg vendor.dat
vendor.fd vendor.flx vendor.frm vendor.k1
vendor.tag venrpt.flx venrpt.rpt version

Glossary

CUA - Common User Access, part of IBM's  SAA

SAA - Systems Application Architecture - a series of interfaces, conventions and protocols which provide a framework for consistent application development and execution
(Source: DataFlex 3.1 User's Guide, page 241.; DataFlex 3.1 UIMS Handbook)

Additional Reading

  1. You may want to check for an updated version of this white paper on our Web site from time to time. Many of our White Papers are updated as information changes. For those papers, the Last Edited date is always at the top of the paper.
  2. Visit the Data Access Worldwide Support Home page for information about all of our support offerings, including free support offerings, such as the Technical Knowledge Base, White Papers and Peer Support Newsgroups: http://www.dataaccess.com/support.
  3. Transformation - Converting DataFlex 2.3b Applications to Revision 3.0, Doug Goldner, Data Access Corporation, 1992, 168 pages. Available from Data Access Corporation or your local distributor.
  4. Migrating to Windows with Visual DataFlex, White Paper, John J. Tuohy, Data Access Corporation, June 6, 1997, Location: http://www.dataaccess.com/WhitePapers.
  5. DataFlex and the Year 2000, White Paper, N. Joe Potts, Data Access Corporation, December 2, 1997, Location: http://www.dataaccess.com/WhitePapers.
  6. DataFlex and DLLs, White Paper, Application Engineering Group, Data Access Corporation, April 25, 1996, Location: http://www.dataaccess.com/WhitePapers.
  7. Data Definition in Visual DataFlex, White Paper, Data Access Nederland, December 17, 1998, Location: http://www.dataaccess.com/WhitePapers.
  8. Transactions in DataFlex 3.1, White Paper, Application Engineering Group, Data Access Corporation, April 25, 1996, Location:
  9. DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
  10. Online Documentation for Visual DataFlex (all revisions of VDF).
  11. Windows User's Guide to DOS : Using the Command Line in Windows 95/98, Carolyn Z. Gillay & Bette A. Peat, September 1998, Franklin Beedle & Assoc; ISBN: 1887902422.
  12. DFConver utility, Location: ftp://ftp.dataaccess.com/pub/products/dataflex/tools.

    13. Note: There is a lot of useful information in all of the DataFlex documentation. Some of the most useful files for the topic of this paper are in the electronic documentation files that can be read with the Adobe Acrobat reader.

Contacting Data Access Worldwide

Data Access Worldwide
14000 SW 119 Ave
Miami, FL 33186
305-238-0012
Domestic Sales: 800-451-3539
Fax: 305-238-0017
email: sales@dataaccess.com
Newsgroup Server: news.dataaccess.com
Internet: http://www.dataaccess.com

Data Access Worldwide - Asia Pacific
Suite 5, 333 Wantirna Road, Wantirna VIC 3152 Australia
Phone: +61 3 9800 4233 f: +61 3 9800 4255
Sales: asiapacific@DataAccess.com
Support: support.asiapacific@DataAccess.com
Internet: http://www.DataAccess.com/AsiaPacific

Data Access Worldwide - Brasil
Av.Paulista, 1776 - 21st.Floor
São Paulo -SP - Brazil
CEP 01310-921
Phone: 5511-3262-2000
Fax 5511-3284-1579
Sales: info@dataaccess.com.br
Support: suporte@dataaccess.com.br
Internet: http://www.dataaccess.com.br

Data Access Worldwide - Europe
Lansinkesweg 4
7553 AE Hengelo
The Netherlands
Telephone: +31 (0)74 - 255 56 09
Fax: +31 (0)74 - 250 34 66
Sales: info@dataaccess.nl
Support: support@dataaccess.nl
Internet: http://www.dataaccess.nl

Data Access Technical Support
800-451-3539 / 305-232-3142
email: support@dataaccess.com
Visit our Support Home page to see all of our Support options: http://www.dataaccess.com/support

Data Access Technical Knowledge Base    http://www.dataaccess.com/kbase.asp
Many answers to technical problems can be found online in the Data Access Technical Knowledge Base. Here, you can access the same live data that Data Access Worldwide technical support and development staff use to enter and track technical articles.

Copyright Notice
This document is property of Data Access Corporation. With credit to Data Access Corporation for its authorship, you are encouraged to reproduce this information in any format either on paper or electronically, in whole or in part. You may publish this paper as a stand alone document within your own publications conditional on the maintenance of the intent, context, and integrity of the material as it is presented here.

DataFlex is a registered trademark of Data Access Corporation.

NO LIABILITY FOR CONSEQUENTIAL DAMAGES
To the maximum extent permitted by applicable law, in no event shall Data Access Corporation be liable for any special, incidental, indirect, or consequential damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use any information provided in this document, even if Data Access Corporation has been advised of the possibility of such damages. Because some states and jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you.