View source for Upgrading to DataFlex 3.2

Before you read any further, you need to be aware that DataFlex 3.2 Character Mode is a legacy, unsupported product. That said, we know there are still organisations working with earlier versions of DataFlex Character Mode, who may want to upgrade to v3.2.

This page should be read by anyone upgrading to DataFlex 3.2 from any prior revision. It discusses issues commonly encountered when upgrading. 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.

The content of this page is based on a whitepaper originally written in May 1998 by Dennis Piccioni from Data Access Worldwide. Updates were made to the content up until 2002, but nothing after that, so some references will be dated.

== 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:

*; Supported Platforms
: DataFlex 3.2 is tested and supported under the following current operating systems and network operating systems:

:* DOS 6.22
:* Microsoft Windows 98 SE
:* Microsoft Windows NT 4 SP6a Workstation and Server
:* Windows 2000 SP1
:* SCO Unixware / SCO 7
:* Hewlett-Packard HP-UX 10.20
:* IBM AIX 4.2
:* SCO UNIX Open Server Enterprise 5.04
:* Sun Solaris 2
:* Red Hat Linux version 5.0 (and higher), kernel 2.2.14 (and higher)
:* Caldera Linux version 1.2 (and higher), kernel 2.2.14 (and higher)

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.

*; DOS and Console Mode Runtimes
:Under Windows 98, ME, NT 4, 2000 and XP, you have a choice of 2 different runtimes for running your DataFlex application. DataFlex 3.2 comes with the standard DOS runtime, dfrun.exe, and a Windows console mode runtime, dfruncon.exe, which gives you several features unique to Windows applications:

:* The ability to load drivers, such as the DataFlex Btrieve driver and the DataFlex ODBC driver.
:* Use the Windows memory manager instead of the DOS4G memory manager that the DOS runtime uses.
:* Ability to make DLL calls. See the white paper DataFlex and DLLs for more information on this topic.
:* Both dfrun.exe and dfruncon.exe are 32-bit programs.
:*  No recompilation is necessary, simply run dfrun or dfruncon, depending on your need.

*;Object-oriented programming
:DataFlex was the first fully object-oriented 4th generation programming language (4GL). However, it still fully supports procedural code (in character-mode revisions, not VDF), and even mixed-mode programming.

*;Extended Filelist 

: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.

*;Index Optimization
: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.

*;Lock Optimization
: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.

*;Changing Data File Definitions in a DataFlex Program
: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:

:* Set_Attribute command
:* Structure_Start command
:* Structure_End command

*;Text and Binary Field Support
:These new field types were added in DataFlex revision 3.0.

*;Character Mode DataDictionary Support
:The proven DataDictionary technology from Visual DataFlex is integrated into and fully supported in DataFlex 3.2.

== Running on Linux and Unix ==

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

*;Path Separator
: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:

<source lang="vdf">
String sDirSeparator
move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator
</source>

*;Install Location
: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'''.

*;Batch files versus Shell Scripts
:Where batch files are used in DOS/Windows environments, shell scripts are used in Linux/Unix.

*;File Casing
: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:

<source lang="vdf">
cd /usr/local/df32/mysourcecode
lcase
</source>

*;Binary Compatibility
: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.1 & Visual DataFlex
: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.

*;DataFlex 3.0 - 3.05
:Data files created between revisions 3.0 and 3.05 have the same file format as DataFlex 3.2 and VDF. However, some bits of the data file were unused at the time. One of these bits is used in DataFlex 3.2 for the Transaction Type setting.

*;DataFlex 2.3b
:Data files from revision 2.3b can be accessed by all current DataFlex revisions, so it is not necessary to upgrade the file format. If any change to the file definition a 2.3b data file is made using revision 3.X, the file format is automatically updated to the format of that revision.

:There are several valid and useful reasons to upgrade your data files to 3.2/VDF format. This format has several new capabilities and features:

::;* Header Integrity Checking (Introduced in 3.0)
::: this creates a .hdr file for the specified .dat file, which contains a copy of the data file's header. Sometimes when a data file is corrupted, the corruption is only in the header of the data file. In that case, if header integrity checking is turned on, this can be fixed easily.
::;* Dynamic Data Compression (Introduced in 3.0)
::: There are three types of on-the-fly data compression available, which saves hard disk space with very little overhead.
::;* Transaction Tracking Support (Introduced in 3.1)
::: Support for Novell Netware's Transaction Tracking (TTS). This creates much better data integrity and transaction support when using Netware. <br> Data files created in DataFlex revisions prior to 3.1 will default to a Transaction Type setting of Client_Atomic, which is also the default setting when creating a new data file in DataFlex 3.2.

*;DataFlex Pre-2.3b Revisions (Revisions 2.1 - 2.2)
: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.

*;DataFlex Pre-2.1 Revisions (2.0e and below)
: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:

::* Pre-2.3b to 2.3b (and higher)
::* 2.3b to 3.X/VDF
: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.

*;Converting Data Files to Revision 3.2 Format
:If you do want to convert all your data files to 3.2 format, you can do so using the DFMaint utility:

# Go to a command prompt.
# Run \df32\usr\setpath.bat or other batch process to set your environment for DataFlex 3.2.
# Run DFMaint.exe.
# Select "Filelist" from the "Maintenance" menu.
# Highlight the file to convert - To select all files, choose "Select All" from the "Filelist" menu.
# Choose "Convert" from the "Database" menu.
# 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 ==

* In order to upgrade to a newer revision of DataFlex, you must recompile your source code file(s) to create new DataFlex programs.
** FOR EXAMPLE: A program compiled under DataFlex revision 2.3b will not run under revision 3.2.
** EXCEPTION: You <u>can</u> run programs compiled under DataFlex revision 2.3 with a 3.0 or 3.01 runtime.
* You can run programs compiled with the same major revision but a different letter revision, but we recommend always recompiling and running using the identical 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.

== 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:

*termlist.cfg & *.dfr for registration information
*filelist.cfg
*data files: *.dat, *.fd, *.k*, *.tag, *.hdr, *.vld
*compiled DataFlex programs: *.flx
*source code for DataFlex programs: *.src, *.frm, *.inc, *.pkg, ...

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 for running DataFlex 3.2==

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. 

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).

== 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'''

 Target or Command Line: c:\windows\command.com

This launches a DOS session under Windows.

 Working: c:\app\data

Starts the session in the specified directory.

Batch File: c:\df32\usr\setpath.bat

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'''

 Target or Command Line: c:\winnt\system32\cmd.exe

All other parameters are the same as the Windows 95/98/ME example above.
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)

DataFlex 3.2 comes with an object-oriented,  [[#CUA]] compliant menu program. This is the default menu that will run with DataFlex 3.2.
If you wish to use a menu program that more closely resembles the 2.3b style menu program, you can compile menuold.src (\df32\src\source\menuold.src) and then either execute "dfrun menuold" to access this menu or rename menuold.flx to menu.flx to have this menu be used as the default.
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 ==

Date Format
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.

Transaction Tracking
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.

Data Format
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:

<source lang="vdf">
Integer iRev
Open CUSTOMER
Get_Attribute DF_File_Revision of CUSTOMER.File_Number to iRev
Showln "File Revision of Customer File: " iRev "."
</source>

Expression Evaluation

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

*The standard mathematical logical operators (<, >, >=, <>,etc.) can be used in addition to the DataFlex logical operators used in DataFlex 2.3b (LT, GT, GE,etc.), provided the expression is used in parentheses.
*The Boolean logic operators AND and OR have been added.

*The MIN and MAX operators have been added to replace the use of < and > for this purpose, since < and > are now used as logical operators. It is important to realize how this affects evaluation of program code:
:Let's use an example to illustrate this. Look at the following line of DataFlex code:

<source lang="vdf">
showln (4 > 5)
</source>

:In DataFlex 2.3b, this line would evaluate to show "5".

:In DataFlex 3.2, this line will evaluate to show "0" (meaning "False", since 4 is not greater than 5).

:The corrected line of code for DataFlex 3.2 to evaluate as it did in DataFlex 2.3 would be:

<source lang="vdf">
showln (4 MAX 5)
</source>

*The mathematical operators can now be used on strings, making their function more intuitive and compatible with other programming environments. However, this will result in some expressions evaluating differently in DataFlex 3.x than they did in 2.3.

: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:

<source lang="vdf">
String A
String B
Move "3" to A
Move "2" to B
</source>


:{| class="wikitable"
!colspan="1"|
!colspan="2"|'''Results'''
|-
|'''Expression'''
|'''DataFlex 2.3b'''
|'''DataFlex 3.2'''
|-
|showln (A + B)
|style="text-align:center;" | 5
|style="text-align:center;" | "32"
|-
|showln (A * B)
|style="text-align:center;" | 6
|style="text-align:center;" | "3 2"
|-
|showln (A - B)
|style="text-align:center;" | 1 
|style="text-align:center;" | "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 ==

* In DataFlex 3.2, a compiled DataFlex program (a .flx file) will only be created if your source code compilation does not generate any errors.
* The DataFlex 2.3 compiler was very forgiving; it allowed numerous types of incorrect syntax without generating error messages. The newer compiler version has been improved and will often catch errors the 2.3b compiler did not.
: 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, the compiler flag -x23 is provided (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 article 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 ==

===Error 4155 "Edit Requires Reread or Lock During Save"===

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:

Whenever a new record is created (i.e. a value is moved to a file.field) a lock command must first be issued. A lock command locks all open data files that are not in read_only mode.
Whenever an existing record is edited, a reread command of the corresponding data file must first be issued. A reread command rereads all data files specified as arguments for the command and then issues a lock command.
Whenever an existing record is deleted, the affected data file must be in a locked state.
For each lock command issued one unlock command must be issued.
For each reread command issued one unlock command must be issued.
See the DataFlex Encyclopedia for more information on the lock, reread and unlock commands.
You must use multiuser licenses for all versions of DataFlex that share data files, because file locking is suppressed in single-user runtimes.

====How to write correct code for Multiuser Coding Examples:====

'''Creating a new record:'''

<source lang="vdf">
clear NEWFILE
lock
    move VAR to NEWFILE.FIELD
    saverecord NEWFILE
unlock
</source>

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.

'''Editing an existing record:'''
<source lang="vdf">
reread FILE
    move VAR to FILE.FIELD
    saverecord FILE
unlock
</source>

'''Copying data from an existing record in FILE to a new record in NEWFILE:'''
<source lang="vdf">
reread FILE
    move FILE.FIELD to NEWFILE.FIELD
    saverecord NEWFILE
unlock
</source>

Explanation of terms:

*NEWFILE is a data file where a new record is being created
*FILE is a data file with an existing record
*VAR is a variable in the program code

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.

===Error 4098 "Bad Relationship"===
Error encountered by 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.

===Error 4141 "Data set files must support transaction"===
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.

===Zerofile command===
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.

===Modified Runtimes===
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:

*Editing of filelist entries, even for multiple filelists, not just the current one (like DFMaint allows).
*It allows for mass-manipulation of data files unlike other utilities, like DFFile, which can only manipulate one file at a time.
*Accepts command line parameters for all filelist and index manipulation.
*Can convert datafiles to and from other database formats (i.e. Btrieve, DB2, ODBC) using DataFlex loadable drivers.

===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:

*Accelerator key definition
*Color settings
*Appearance settings for things like currency
*Date and number format settings
*Other miscellaneous settings

===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:

*Indexing utility
*Cleanup utility
*Editing of filelist entries

===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 and the Year 2000, N. Joe Potts, Data Access Corporation, December 2, 1997.
*Installation & Environment Guide for all Y2K Enhanced revisions of DataFlex.
*Online Documentation for Visual DataFlex (all revisions of VDF).

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:

'''Epoch_Value'''

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):

*If a user enters "010198" into a date window, it will be converted to "01/01/1998".
*If a user enters "010102" into a date window, it will be converted to "01/01/2002".

'''SysDate4_State'''

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

'''Date4_State'''

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.

In character-mode revisions, in date windows with only 2 digits for the date, the LAST 2 digits are displayed:

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

===Conv2000 Utility===
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===

'''DataFlex 3.2'''

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:

<source lang="vdf">
Use y2k.pkg
</source>

'''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:

<source lang="vdf">
Set_Date_Attribute Sysdate4_State to DFTrue
</source>

: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.

<source lang="vdf">
Set_Date_Attribute Date4_State to DFTrue
</source>

: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.

<source lang="vdf">
Set_Date_Attribute Epoch_Value to 30
</source>

: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)

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.

*Keep one copy of the source code in the 2.3b area and another copy in the 3.2 area. This allows you to edit either version of the source code without affecting the other.
*Create a shared data directory.
*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.)
*How to run DataFlex 3.2 and other (prior) revisions concurrently.

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:

:::*all data files for your application (*.dat, *.k*, *.tag, *.fd, *.def)
:::*filelist.cfg

:::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.

:::*all source code files (*.frm, *.src, *.inc, *.rpt, …)

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

:::*the most important are the executable files (*.exe) and termlist.cfg
:::*see Appendix A for a complete list of files that are installed by a DataFlex 2.3b Development License – these are the files that should remain in the c:\df23 directory

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

:For the remainder of this article 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:'''

*DOS/Windows: Remember to execute the c:\df32\usr\setpath.bat batch file before running DFSetup.exe to install your registration code.
*Linux/Unix: Remember to execute the /usr/local/df32/usr/setpath script before running dfsetup to install your registration code.

'''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;</br>c:\df32\src\pkg;c:\df32\usr\examples\expense;</br>c:\df32\usr\examples\dar;c:\df32\usr\examples\ordentry;</br>c:\df32\usr\examples\big;c:\df32\usr\examples\report;</br>c:\df32\usr\examples\data;


::After:

:::dfpath='''.;c:\app\data;'''c:\df32\usr;c:\df32\usr\help;c:\df32\lib;</br>c:\df32\bin;c:\df32\src\pkg;c:\df32\usr\examples\expense;</br>c:\df32\usr\examples\dar;c:\df32\usr\examples\ordentry;</br>c:\df32\usr\examples\big;c:\df32\usr\examples\report;</br>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

#Switch to c:\df23 directory
#Set the DFPATH environment variable - '''set DFPATH=.;c:\app\data'''
#Make sure c:\df23 is in your PATH environment variable
#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 ==

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.

Visit the '''Data Access Support Forums''': https://support.dataaccess.com/.

'''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.

'''Migrating to Windows with Visual DataFlex''', White Paper, John J. Tuohy, Data Access Corporation, June 6, 1997, Location: http://www.dataaccess.com/WhitePapers.

'''DataFlex and the Year 2000''', White Paper, N. Joe Potts, Data Access Corporation, December 2, 1997, Location: http://www.dataaccess.com/WhitePapers.

'''DataFlex and DLLs''' White Paper, Application Engineering Group, Data Access Corporation, April 25, 1996, Location: http://www.dataaccess.com/WhitePapers.

'''Data Definition in Visual DataFlex''', White Paper, Data Access Nederland, December 17, 1998, Location: http://www.dataaccess.com/WhitePapers.

'''Transactions in DataFlex 3.1''', White Paper, Application Engineering Group, Data Access Corporation, April 25, 1996, Location: 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.

'''Online Documentation for DataFlex''': https://docs.dataaccess.com/

'''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.

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

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.

'''The Data Access Knowledge Base''': https://www.dataaccess.com/Resources/Knowledge-Base-1114. 

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.

[[Category:DataFlex (Character Mode)]]