DataFlex Wiki - User contributions [en]

Using the REST Library

2022-01-25T15:39:58Z

Mikepeat: Changing where to get the library

The simple example of a [[RESTful Service Theory|RESTful service]] set out in the article [[A Simple RESTful Service]] involved quite a bit of work to produce an API for only one table.

An alternative approach is to use the REST library I ([[user:mikepeat|Mike]]) have created, which can be downloaded from <s>[[File:RESTLibrary.zip]]</s> (that one now obsolete) [https://github.com/DataFlexCode/UIG-REST-Library here] on [https://github.com/DataFlexCode GitHub/DataFlexCode].

To use it, <s>unzip that file</s> download it (via a Git "pull" request) into some directory, then, from the workspace you are developing in, use that as a library; in the Studio do: Tools --> Maintain Libraries... --> Add Library, then navigate to where you <s>unzipped</s> downloaded it and within it select the "RESTLibrary.sws" file.

That will add a new section to the Studio's Class Palette entitled "REST".

With the WebApp project selected in the Studio, do: File --> New --> Other --> DataFlex Source File, naming it, for this example, "WebOrderAPI", which will create a blank package file. Into that, from the new REST section of the class palette, drag an object of the cRESTfulService class. Rename the object '''oWebOrderAPI'''.

Then again do: File --> New --> Other --> DataFlex Source File, this time naming it '''ApiCustomersHandler'''. Into that blank file drag an object of the cRestResourceHandler class. Change the object's name to oApiCustomersHandler and set its psInterfacePath property (an empty string by default) to "'''customers'''".

Then in the DDO Explorer pane (lower-right in the Studio by default) click the "+" book icon (Add DDO: [[File:Add DD.jpg|15px]]) and select the cCustomerDataDictionary.

Drag a cRESTApiObject from the class palette to below the comment "''Add your cRESTApiObjects here''". Rename it to "oCustomers". Set its phoDD property to oCustomer_DD, its psCollName (collection name) property to "'''customers'''" (plural) and its psInstName (instance name) property to "'''customer'''" (singular).

Uncomment one of the "Send AddListColumn" lines and change its "Table.Column" to '''Customer.Customer_Number''', then copy that line and make the copy for '''Customer.Name'''. (You can keep adding those to your heart's content, but lists should be sparing of such detail.)

Go back to your WebOrderAPI file and under the comment line: 'Add "Use" statements for your cResourceHandler objects here:' add the line: "'''Use APICustomersHandler.pkg'''".

For development you may want to change the pbVerboseErrors setting to True, although for deployment it should probably be set back to False, to avoid confusing users with a pile of technical detail, which they neither should, nor want to, be exposed to.

You should perhaps, for future-proofing a real API, change the psPath setting from its default of "api" to "'''api/v1'''" (to provide for v2, v3 and so on in the future) - Note: this will change the URL which you use to make calls to it.

That should leave you with (some additional comments are mine):

'''WebOrderAPI.pkg''':
<source lang="vdf">
Use cRESTfulService.pkg

Object oWebOrderAPI is a cRESTfulService
Set psPath to "api/v1" // Changed to provide for future versions
Set pbVerboseErrors to True // For development only, return to False for deployment

// Add "Use" statements for your cResourceHandler objects here:
Use APICustomersHandler.pkg // You add this line

Procedure APIRoot
Handle hoResp

Get CreateJsonObject to hoResp
Send AddRegisteredCollections hoResp

Send OutputJson hoResp
End_Procedure

Procedure ProcessHttpRequest String sVerb
String sPart0

Get PathPart 0 to sPart0
Move (Lowercase(sPart0)) to sPart0

Case Begin

Case ((sVerb = C_httpGet) and (sPart0 = ""))
Send APIRoot
Case Break

Case (IsRegisteredPath(Self, sPart0))
Send AutoProcess sPart0
Case Break

Case Else
Send UnrecognisedOperation
Case Break

Case End

End_Procedure

End_Object
</source>

'''APICustomersHandler.pkg''':
<source lang="vdf">
Use cRESTResourceHandler.pkg
Use cCustomerDataDictionary.dd
Use cRESTAPIObject.pkg

Object oAPICustomersHandler is a cRESTResourceHandler
// Add your data-dictionary objects here

// Use the DDO Explorer in the Studio to select DDOs:
Object oCustomer_DD is a cCustomerDataDictionary
End_Object

Set Main_DD to oCustomer_DD

Set psInterfacePath to "customers" // We have to set this

// Add your cRESTApiObjects here (below the Set Main_DD line)

// Simply drag cRESTApiObjects here from the Studio's Class Palette
Object oCustomer is a cRESTApiObject
Set phoDD to oCustomer_DD // We have to set these three
Set psCollName to "customers" // properties for the object
Set psInstName to "customer" // to work properly

// Send AddListColumn File_Field Table.Column
Send AddListColumn File_Field Customer.Customer_Number // These lines determine
Send AddListColumn File_Field Customer.Name // the columns in the list

Procedure PostProc Handle hoResp Integer iMode
Forward Send PostProc hoResp iMode

// Add dependant collections (or other links) in here, e.g.:
// Send AddCollection hoResp "{name}" (InstURL(Self, iMode) + "/{collectionName}")
// Send AddLink hoResp "{name}" {identifier} {URL}
End_Procedure

End_Object

End_Object
</source>

Now you can immediately see the saving: 81 lines (most of which were written for you and a couple of which are comments I have added for clarification) vs. the 574 lines in the [[A Simple RESTful Service|Simple]] example, while most of the functionality is essentially the same (a careful examination will reveal a bit more "[https://en.wikipedia.org/wiki/HATEOAS ''HATEOAS'']"-type information in some of the returned JSON in the former).

In addition, this approach has much more generality and extensibility: additional cRESTApiObjects, and the corresponding DDOs, can be added to the cApiCustomersHandler to provide for dependant sub-collections (since customers have orders, and orders have details), while other cRESTResourceHandler objects can be added to handle other top-level collections (orders, vendors, inventory, salespeople and so on).

The library (in the cRESTApiObjects) provides mechanisms to exclude specific fields from the interface (Send AddExcludeColumn ''Table.Column''), or mark them as read-only through it (Send AddReadOnlyColumn ''Table.Column''), include parent columns in collections or instances (through the AddListColumn and AddInstanceColumn procedures) and even provide calculated pseudo-columns (AddListFunctionColumn and AddInstanceFunctionColumn). Entire collections can be set as read-only (pbReadOnly), no-update (pbNoUpdate) or no-delete (pbNoDelete).

In your browser, or testing tool such as [https://www.getpostman.com/ Postman] or the DataFlex [[Consuming RESTful Services in DataFlex|RESTTest view]] in another article in this series, you can access this one as ".../api/v1" (or just ".../api" if you didn't make the versioning change to the psPath setting).

====Security====

This example does not have any security built into it yet, but the cRESTfulService class does understand a bit about Basic Auth, so we can add the following short OnPreRequest procedure to the oWebOrderAPI object:
<source lang="vdf">
Procedure OnPreRequest String sVerb String sPath
tBasicAuthCredentials tCreds
Boolean bOK

Set psUsername to "" // Reset it to blank at the start of *every* request
Get BasicAuthCredentials to tCreds

If (tCreds.sUserName <> "") Begin
Clear WebAppUser
Move tCreds.sUserName to WebAppUser.LoginName
Find Eq WebAppUser by Index.1

If (Found) Begin
Move (ComparePasswords(ghoWebSessionManager, Trim(WebAppUser.Password), ;
tCreds.sPassword)) to bOK

If bOK ;
Set psUsername to tCreds.sUserName
End

End

End_Procedure
</source>

As you can see, that relies on the ComparePasswords function of the WebSessionManager object, which will not be present in a Basic Web Project, so if using such, you would have to replace that, perhaps with a simple:
<source lang="vdf">
Move (Trim(WebAppUser.Password) = Trim(tCreds.sPassword)) to bOK
</source>
Which assumes that you are not using encrypted passwords, however how to handle those is left as an exercise for the reader!

Then at the top of the file add "'''Open WebAppUser'''", while at the top of the oWebOrderAPI object add "'''Property String psUsername'''".

Finally, right at the beginning of the ProcessHttpRequest procedure add:
<source lang="vdf">
If (psUsername(Self) = "") Begin
Send BasicAuthRequired "Web Order API"
Procedure_Return
End
</source>

Fuller instructions for creating an API using the REST library can be found in [https://docs.google.com/document/d/1N3BvvygKfjKO_5TMosWrR8aahI-5VOz6-z-8jSqA_to/edit?usp=sharing my course notes from Synergy 2019], although complete documentation for the library has sadly yet to make it to the top of my ''ToDo'' pile (it will be a ''lot'' of work).

==See also==

*[[REST]]
*[[RESTful Service Theory]]
*[[RESTful Services in DataFlex]]
*[[Consuming RESTful Services in DataFlex]]
*[[Creating RESTful Services in DataFlex]]
*[[A Simple RESTful Service]]
* https://github.com/DataFlexCode/UIG-REST-Library

[[Category:REST]][[Category:Web Services]]

CIniFile

2021-08-11T08:01:31Z

Mikepeat: Sets _not_ Gets!

An object of the '''cIniFile''' class can be used for reading information avaiable from an INI file.

INI files are often used to store user preferences or setup options for applications.

==INI files==
In [[Visual DataFlex]] you can freely use as many INI files as you require, however the two-level structure of INI files (sections and keys) means that there is often no need to use more than one. Here, for example, is a boot.ini file (usually found in the root directory of the system drive of Windows operating systems):

<source lang="ini">
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(2)\WINDOWS

[operating systems]
multi(0)disk(0)rdisk(0)partition(2)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /NoExecute=OptIn
</source>

As you can see, it defines two sections - [boot loader] and [operating systems] - each with different settings within them.

==Visual DataFlex Workspace files==
Another example are the workspace configuration files used by [[Visual DataFlex]] itself (by default named "Config.ws", showing that they don't have to use the .ini extension - see the article in "See Also" below), which must exist in the same directory the program is run from (usually the "Programs" subdirectory of the workspace). Here is an example:

<source lang="ini">
[Workspace]
Home=..\
AppSrcPath=.\AppSrc
AppHTMLPath=.\AppHtml
BitmapPath=.\Bitmaps
IdeSrcPath=.\IdeSrc
DataPath=.\Data
DDSrcPath=.\DdSrc
HelpPath=.\Help
ProgramPath=.\Programs
FileList=.\Data\Filelist.cfg
Description=MyFirstProject
</source>

Here only a single section - [Workspace] - is defined, however the fact that an INI file can have as many sections as it needs means that you can use this very file to set up options for how you want your program to behave.

Note that section names (the ones in the square brackets), key names ("Home", "AppSrcPath", etc.) and key values can all contain spaces (although for my own part I prefer not to use those and depend on [http://en.wikipedia.org/wiki/Camelcase camelCase] to supply readability).

==INI file advantages==
The advantage of the INI file approach is that it can make programs configurable for different environments or uses without them having to be recompiled with different settings each time: the program can be made with a set of default values which can then be overridden at run-time by the settings in an INI file. It has the advantage over Registry settings, which perform very much the same function, in that you don't need any special rights on the machine to set it up and make changes to it: you are just working with text files, so security policy issues about who has rights to the [http://en.wikipedia.org/wiki/Windows_Registry Windows Registry], or who can run RegEdit or RegEdit32 do not apply - if you can run Notepad and modify files you can configure your application.

Here is an example where an additional section allowing the configuration of a database location and login has been added:

<source lang="ini">
[Workspace]
Home=..\
AppSrcPath=.\AppSrc
AppHTMLPath=.\AppHtml
BitmapPath=.\Bitmaps
IdeSrcPath=.\IdeSrc
DataPath=.\Data
DDSrcPath=.\DdSrc
HelpPath=.\Help
ProgramPath=.\Programs
FileList=.\Data\Filelist.cfg
Description=MyFirstProject

[Database Login]
Server=big-iron.database-servers.local
Login=itsme
Password=letmein
Database=Accounting
Driver=MSSQLDRV
</source>
Combining these factors - the fact that there is probably no need to have more than one INI file, and the fact that [[Visual DataFlex]] requres one anyway - means that for most purposes you can just add what you need to the existing workspace configuration file.

==Accessing INI files==
So how do you access that information in your program?

For most purposes the information in an INI file will only be read at program start-up. This means that (a) the oApplication object is a good place to do such things (see the article in "See Also" below for some guidance on sub-classing the cApplicatiion class) and (b) the cIniFile object need not be retained after it has been used. (Of course you might have different requirements, but here we will assume these are true.)

So... in your oApplication object (perhaps in the "OnCreate" procedure, perhaps elsewhere, such as in "Construct_Object" or "End_Construct_Object") what you need to do is dynamically create a cIniFile object, use it to get the information you want, then destroy it again. You also want to be able to access the workspace configuration file for the application, perhaps without knowing ahead of time what that is actually called.

Here is one way of doing it ('''''note''' - this code is assumed to be in the oApplication object or a sub-class of the cApplication class; the only place this matters is in the "Set psFileName ..." line, where "Self" will refer to the oApplication object, and where the various properties are held''):

<source lang="vdf">
String sServer sLogin sPW sDrv sDB
Boolean bLogin
Handle hoIni

// Retrieve your application defaults into local variables
Get psServer to sServer
Get psLogin to sLogin
Get psPassword to sPW
Get psDriver to sDrv
Get psDatabase to sDB
Get pbDoLogin to bDB

Get Create U_cIniFile to hoIni // Create INI file object

// Make it use the workspace configuration file
Set psFileName of hoIni to (psWorkspaceWSFile(phoWorkspace(Self)))

// Read the information
Move (ReadString(hoIni, "Database Login", "Server", sServer)) to sServer
Move (ReadString(hoIni, "Database Login", "Login", sLogin)) to sLogin
Move (ReadString(hoIni, "Database Login", "Password", sPW)) to sPW
Move (ReadString(hoIni, "Database Login", "Driver", sDrv)) to sDrv
Move (ReadString(hoIni, "Database Login", "Database", sDB)) to sDB
Move (ReadString(hoIni, "Database Login", "DoLogin", bLogin)) to bLogin

Send Destroy of hoIni // And Destroy it again

// Set the properties to make the information persistent
Set psServer to sServer
Set psLogin to sLogin
Set psPassword to sPW
Set psDriver to sDrv
Set psDatabase to sDB
Set pbDoLogin to bDB
</source>

The above code will retrieve the values set in the second workspace file example above. Note that in that example, the "DoLogin" value is not present - the "''ReadString''" method of the cIniFile class lets you supply a default value to use if the setting is not present, and here we have used the bLogin variable, which was set from the pbDoLogin property, and which is then used to set that property again... so the fact that the setting is absent (not "''missing''" - it is deliberate!) means that the default property remains unchanged.

You could save some code by not retrieving the properties into local variables first, but using the properties as defaults directly:

<source lang="dataflex">
Move (ReadString(hoIni, "Database Login", "Server", psServer(Self))) to sServer
Move (ReadString(hoIni, "Database Login", "Login", psLogin(Self))) to sLogin
Move (ReadString(hoIni, "Database Login", "Password", psPassword(Self))) to sPW
Move (ReadString(hoIni, "Database Login", "Driver", psDriver(Self))) to sDrv
Move (ReadString(hoIni, "Database Login", "Database", psDatabase(Self))) to sDB
Move (ReadString(hoIni, "Database Login", "DoLogin", pbDoLogin(Self))) to bLogin
</source>

Or even dispense with the local variables completely:

<source lang="dataflex">
Set psServer to (ReadString(hoIni, "Database Login", "Server", psServer(Self)))
Set psLogin to (ReadString(hoIni, "Database Login", "Login", psLogin(Self)))
Set psPassword to (ReadString(hoIni, "Database Login", "Password", psPassword(Self)))
Set psDriver to (ReadString(hoIni, "Database Login", "Driver", psDriver(Self)))
Set psDatabase to (ReadString(hoIni, "Database Login", "Database", psDatabase(Self)))
Set pbDoLogin to (ReadString(hoIni, "Database Login", "DoLogin", pbDoLogin(Self)))
</source>

But some might consider that a bridge too far!

==Summary==
The cIniFile has other methods as well: it can write as well as read (WriteString, DeleteKey and DeleteSection) and can dynamically determine the contents of the file (ReadSections, ReadSection, SectionExists and KeyExists) - see the VDF Help for full information - but the ReadString method is the one you will need in most circumstances.

== See Also ==

[[Passing the workspace as a parameter]]

== External references ==
* http://en.wikipedia.org/wiki/INI_file

[[Category: Tutorials]] [[Category: Cookbook]]

Upgrading to DataFlex 3.2

2021-05-20T13:27:38Z

Mikepeat: Location

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

===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"====
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.

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

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

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

Upgrading to DataFlex 3.2

2021-05-20T13:23:19Z

Mikepeat: Splitting lines

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

===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"====
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.

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

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

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

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

Upgrading to DataFlex 3.2

2021-05-20T12:50:58Z

Mikepeat: Lines

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

===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"====
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.

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

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

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-20T12:45:59Z

Mikepeat: Utilities headings

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

===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"====
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.

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

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-20T12:43:19Z

Mikepeat: Runtime errors headings

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

===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"====
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.

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

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T18:00:29Z

Mikepeat: Headings

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:58:57Z

Mikepeat: Spacing

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:56:42Z

Mikepeat: Lists

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

*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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:50:15Z

Mikepeat: Heading

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:49:36Z

Mikepeat: Headings

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:45:17Z

Mikepeat: Code

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:42:34Z

Mikepeat: Indent

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:33:58Z

Mikepeat: Formatting

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:32:29Z

Mikepeat: Tidy

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:30:03Z

Mikepeat: Indent

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:26:25Z

Mikepeat: Indent

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:23:43Z

Mikepeat: Files list

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:16:31Z

Mikepeat: Code

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:13:30Z

Mikepeat: Indent

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:12:03Z

Mikepeat: Code

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T17:11:15Z

Mikepeat: Code

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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:

showln (4 > 5)

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:

showln (4 MAX 5)

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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T11:18:07Z

Mikepeat: Tabs away!

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.

Online Documentation for Visual DataFlex (all revisions of VDF).

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.

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.

Upgrading to DataFlex 3.2

2021-05-19T11:11:33Z

Mikepeat: Formatting

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.

Online Documentation for Visual DataFlex (all revisions of VDF).

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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:52:15Z

Mikepeat: Formatting & updated forums

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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

DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.

Online Documentation for Visual DataFlex (all revisions of VDF).

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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:46:38Z

Mikepeat: Bolding & lists

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:44:00Z

Mikepeat: Source

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:39:51Z

Mikepeat: Casing

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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: " (String(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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:37:01Z

Mikepeat: underscore

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:35:57Z

Mikepeat: List

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:34:45Z

Mikepeat: List

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:32:50Z

Mikepeat: Code sample

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:

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Upgrading to DataFlex 3.2

2021-05-19T10:30:48Z

Mikepeat: Marking code samples

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:

::String sDirSeparator
::move (Sysconf (SYSCONF_DIR_SEPARATOR)) to sDirSeparator

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

::cd /usr/local/df32/mysourcecode
::lcase

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

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

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 a brand new, 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>

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

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

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

Editing an existing record:
reread FILE
move VAR to FILE.FIELD
saverecord FILE
unlock

Copying data from an existing record in FILE to a new record in NEWFILE:
reread FILE
move FILE.FIELD to NEWFILE.FIELD
saverecord NEWFILE
unlock

* 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"
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.

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:

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)

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:

Concurrently run DataFlex 2.3b and 3.2 (or just 3.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 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:

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

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 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.
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:
DataFlex 3.2 Installation & Environment Guide, DataFlex 3.2 CD, Data Access Corporation.
Online Documentation for Visual DataFlex (all revisions of VDF).
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.

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.

Using your own user table in WebApps

2021-05-02T10:38:13Z

Mikepeat: UserLogin

In most cases when creating a WebApp for an existing (Windows) system, that system will already have a mechanism for checking user credentials (i.e. user-name and password) in existance. The Data Access supplied mechanism for WebApps uses its own tables for this and for session management within that. So how do we integrate the two?

Actually it is reasonably simple, but I'm going to go through it line-by-line, so it will seem like a lot, but it really isn't.

The instructions below assume that your system has a user table; that it has a userID column of some sort; that column is the primary (unique) key; and that column is the sole element of Index.1 on that table. (If that last is not the case, you will have to also modify the "Send Find of hoUserDD EQ Index.1" line in the UserLogin procedure in your sub-class to use the correct index.)

Text in {''italics''} should be replaced with the appropriate values for your own system.

====Step 1. If you have not already done it, Create a WebApp Project in your workspace.====

====Step 2. From {''DataFlexInstalledLocation''}\Pkg:====

# Copy cWebSessionManagerStandard.pkg (note: not cWebSessionManager.pkg) to your AppSrc directory, renaming it to cWebSessionManager{''YourSystemName''}.pkg
# Copy cWebAppUserDataDictionary.pkg and cWebAppSessionDataDictionary.pkg to your DDSrc directory (the former will not actually be used, but will be modified by the next step of the process, so best to copy it too)

====Step 3. Change the relationship of WebAppSession to WebAppUser to point to your user table instead:====

#The relationship needs to be on identically defined columns (same type and size). I don't think that we ought to impact the existing system when that can be avoided, so if a change is needed (and it usually will be) the change should be at the WebAppSession table end. Modify (in the Studio, right-click WebAppSession in the Table Explorer pane/tab, select "Edit Table" and make the required change to the LoginName column) that so that it matches the (unique) primary key (the user ID) of your current user table. (So if your current user table has a column - say, UserID - which is ASCII 10, modify WebAppSession.LoginName to be ASCII 10 from its original ASCII 20.)
#In the "Relationships" tab, delete the relationship to WebAppUser (the only one there) and add a replacement pointing to your user table, from LoginName on WebAppSession, to whatever the user ID column is on your user table.

====Step 4. Modify your cWebSessionManager sub-class:====

#Change the use statement: "Use cWebSessionManager.pkg" to "Use cWebSessionManagerStandard.pkg"
#Replace the use statement: replace "Use cWebAppUserDataDictionary.dd" with "Use c{''YourUserTable''}DataDictionary.dd"
#Change the classname: from "Class cWebSessionManagerStandard is a cWebSessionManager" to "Class cWebSessionManager{''YourSystemName''} is a cWebSessionManagerStandard" (so sub-classing cWebSessionManagerStandard)
#Change the user data dictionary instance: in the '''Construct_Object''' procedure change "Get Create (RefClass(cWebAppUserDataDictionary)) to hoUserDD" to "Get Create (RefClass(c{''YourUserTable''}DataDictionary)) to hoUserDD"
#Modify the '''UserLogin''' function:
##Replace the line: "Move sLoginName to WebAppUser.LoginName" with "Move sLoginName to {''YourUserTable''}.{''YourIdCol''}
##Replace the line: "If (Found and (Lowercase(sLoginName) = Lowercase(Trim(WebAppUser.LoginName)))) Begin" with "If (Found and (Lowercase(sLoginName) = Lowercase(Trim({''YourUserTable''}.{''YourIdCol''})))) Begin"
##Replace the line: "Get Field_Current_Value of hoUserDD Field WebAppUser.Password to sUserPassword" with "Get Field_Current_Value of hoUserDD Field {''YourUserTable''}.{''YourPasswordCol''} to sUserPassword"
##Replace the line: "Set Field_Changed_Value of hoUserDD Field WebAppUser.LastLogin to (CurrentDateTime())" with "Set Field_Changed_Value of hoUserDD Field {''YourUserTable''}.{''YourLastLoginCol''} to (CurrentDateTime())" // This one is optional. You may not have such a column (a date, by default) and if you do not wish to create one just remove the line
#Modify the '''UpdateSessionProperties''' function:
##Replace the line "Set psUsername to (Trim(WebAppUser.FullName))" with "Set psUsername to (Trim({''YourUserTable''}.{''YourUserFullname''}))" // Optional - otherwise just remove the line
##Replace the line "Set psLoginName to (Trim(WebAppUser.LoginName))" with "Set psLoginName to (Trim({''YourUserTable''}.{''YourIdColumn''}))
##Replace the line: "Set piUserRights to WebAppUser.Rights" with "Set piUserRights to {''YourUserTable''}.{''YourRightsColumn''} // Optional - if you don't have a rights column, remove the line. Note: if you use an ASCII column, rather than a numeric one for this, you will need to add a different property in the Construct_Object procedure of the class - something like "Property String psUserType" and "Set" that instead
#Remove all the other methods from your sub-class (they are covered in its super-class cWebSessionManagerStandard):
##CreateSession
##ValidateSession
##IsLoggedIn
##ComparePasswords
##OnSessionPropertiesSet
##OnSessionPropertiesClear
##EndSession

====Step 5. Modify SessionManager.wo to use your sub-class:====

#Change: "Use cWebSessionManagerStandard.pkg" to "Use cWebSessionManager{''YourSystemName''}.pkg"
#Change: "Object oSessionManager is a cWebSessionManagerStandard" to "Object oSessionManager is a cWebSessionManager{''YourSystemName''}"

Now you should be good to go and users of your Windows app will/can also be users of your WebApp!

Using your own user table in WebApps

2021-04-30T14:02:04Z

Mikepeat: Minor edit

In most cases when creating a WebApp for an existing (Windows) system, that system will already have a mechanism for checking user credentials (i.e. user-name and password) in existance. The Data Access supplied mechanism for WebApps uses its own tables for this and for session management within that. So how do we integrate the two?

Actually it is reasonably simple, but I'm going to go through it line-by-line, so it will seem like a lot, but it really isn't.

The instructions below assume that your system has a user table; that it has a userID column of some sort; that column is the primary (unique) key; and that column is the sole element of Index.1 on that table. (If that last is not the case, you will have to also modify the "Send Find of hoUserDD EQ Index.1" line in the Userlogin procedure in your sub-class to use the correct index.)

Text in {''italics''} should be replaced with the appropriate values for your own system.

====Step 1. If you have not already done it, Create a WebApp Project in your workspace.====

====Step 2. From {''DataFlexInstalledLocation''}\Pkg:====

# Copy cWebSessionManagerStandard.pkg (note: not cWebSessionManager.pkg) to your AppSrc directory, renaming it to cWebSessionManager{''YourSystemName''}.pkg
# Copy cWebAppUserDataDictionary.pkg and cWebAppSessionDataDictionary.pkg to your DDSrc directory (the former will not actually be used, but will be modified by the next step of the process, so best to copy it too)

====Step 3. Change the relationship of WebAppSession to WebAppUser to point to your user table instead:====

#The relationship needs to be on identically defined columns (same type and size). I don't think that we ought to impact the existing system when that can be avoided, so if a change is needed (and it usually will be) the change should be at the WebAppSession table end. Modify (in the Studio, right-click WebAppSession in the Table Explorer pane/tab, select "Edit Table" and make the required change to the LoginName column) that so that it matches the (unique) primary key (the user ID) of your current user table. (So if your current user table has a column - say, UserID - which is ASCII 10, modify WebAppSession.LoginName to be ASCII 10 from its original ASCII 20.)
#In the "Relationships" tab, delete the relationship to WebAppUser (the only one there) and add a replacement pointing to your user table, from LoginName on WebAppSession, to whatever the user ID column is on your user table.

====Step 4. Modify your cWebSessionManager sub-class:====

#Change the use statement: "Use cWebSessionManager.pkg" to "Use cWebSessionManagerStandard.pkg"
#Replace the use statement: replace "Use cWebAppUserDataDictionary.dd" with "Use c{''YourUserTable''}DataDictionary.dd"
#Change the classname: from "Class cWebSessionManagerStandard is a cWebSessionManager" to "Class cWebSessionManager{''YourSystemName''} is a cWebSessionManagerStandard" (so sub-classing cWebSessionManagerStandard)
#Change the user data dictionary instance: in the '''Construct_Object''' procedure change "Get Create (RefClass(cWebAppUserDataDictionary)) to hoUserDD" to "Get Create (RefClass(c{''YourUserTable''}DataDictionary)) to hoUserDD"
#Modify the '''UserLogin''' function:
##Replace the line: "Move sLoginName to WebAppUser.LoginName" with "Move sLoginName to {''YourUserTable''}.{''YourIdCol''}
##Replace the line: "If (Found and (Lowercase(sLoginName) = Lowercase(Trim(WebAppUser.LoginName)))) Begin" with "If (Found and (Lowercase(sLoginName) = Lowercase(Trim({''YourUserTable''}.{''YourIdCol''})))) Begin"
##Replace the line: "Get Field_Current_Value of hoUserDD Field WebAppUser.Password to sUserPassword" with "Get Field_Current_Value of hoUserDD Field {''YourUserTable''}.{''YourPasswordCol''} to sUserPassword"
##Replace the line: "Set Field_Changed_Value of hoUserDD Field WebAppUser.LastLogin to (CurrentDateTime())" with "Set Field_Changed_Value of hoUserDD Field {''YourUserTable''}.{''YourLastLoginCol''} to (CurrentDateTime())" // This one is optional. You may not have such a column (a date, by default) and if you do not wish to create one just remove the line
#Modify the '''UpdateSessionProperties''' function:
##Replace the line "Set psUsername to (Trim(WebAppUser.FullName))" with "Set psUsername to (Trim({''YourUserTable''}.{''YourUserFullname''}))" // Optional - otherwise just remove the line
##Replace the line "Set psLoginName to (Trim(WebAppUser.LoginName))" with "Set psLoginName to (Trim({''YourUserTable''}.{''YourIdColumn''}))
##Replace the line: "Set piUserRights to WebAppUser.Rights" with "Set piUserRights to {''YourUserTable''}.{''YourRightsColumn''} // Optional - if you don't have a rights column, remove the line. Note: if you use an ASCII column, rather than a numeric one for this, you will need to add a different property in the Construct_Object procedure of the class - something like "Property String psUserType" and "Set" that instead
#Remove all the other methods from your sub-class (they are covered in its super-class cWebSessionManagerStandard):
##CreateSession
##ValidateSession
##IsLoggedIn
##ComparePasswords
##OnSessionPropertiesSet
##OnSessionPropertiesClear
##EndSession

====Step 5. Modify SessionManager.wo to use your sub-class:====

#Change: "Use cWebSessionManagerStandard.pkg" to "Use cWebSessionManager{''YourSystemName''}.pkg"
#Change: "Object oSessionManager is a cWebSessionManagerStandard" to "Object oSessionManager is a cWebSessionManager{''YourSystemName''}"

Now you should be good to go and users of your Windows app will/can also be users of your WebApp!

Using your own user table in WebApps

2021-04-30T13:48:41Z

Mikepeat: Typo

In most cases when creating a WebApp for an existing (Windows) system, that system will already have a mechanism for checking user credentials (i.e. user-name and password) in existance. The Data Access supplied mechanism for WebApps uses its own tables for this and for session management within that. So how do we integrate the two?

Actually it is reasonably simple, but I'm going to go through it line-by-line, so it will seem like a lot, but it really isn't.

The instructions below assume that your system has a user table; that it has a userID column of some sort; that column is the primary (unique) key; and that column is the sole element of Index.1 on that table. (If that last is not the case, you will have to also modify the "Send Find of hoUserDD EQ Index.1" line in the Userlogin procedure in your sub-class to use the correct index.)

Text in {''italics''} should be replaced with the appropriate values for your own system.

====Step 1. If you have not already done it, Create a WebApp Project in your workspace.====

====Step 2. From {''DataFlexInstalledLocation''}\Pkg:====

# Copy cWebSessionManagerStandard.pkg (note: not cWebSessionManager.pkg) to your AppSrc directory, renaming it to cWebSessionManager{''YourSystemName''}.pkg
# Copy cWebAppUserDataDictionary.pkg and cWebAppSessionDataDictionary.pkg to your DDSrc directory (the former will not actually be used, but will be modified by the next step of the process, so best to copy it too)

====Step 3. Change the relationship of WebAppSession to WebAppUser to point to your user table instead:====

#The relationship needs to be on identically defined columns (same type and size). I don't think that we ought to impact the existing system when that can be avoided, so if a change is needed (and it usually will be) the change should be at the WebAppSession table end. Modify (in the Studio, right-click WebAppSession in the Table Explorer pane/tab, select "Edit Table" and make the required change to the LoginName column) that so that it matches the (unique) primary key (the user ID) of your current user table. (So if your current user table has a column - say, UserID - which is ASCII 10, modify WebAppSession.LoginName to be ASCII 10 from its original ASCII 20.)
#In the "Relationships" tab, delete the relationship to WebAppUser (the only one there) and add a replacement pointing to your user table, from LoginName on WebAppSession, to whatever the user ID column is on your user table.

====Step 4. Modify your cWebSessionManager sub-class:====

#Change the use statement: "Use cWebSessionManager.pkg" to "Use cWebSessionManagerStandard.pkg"
#Replace the use statement: replace "Use cWebAppUserDataDictionary.dd" with "Use c{''YourUserTable''}DataDictionary.dd"
#Change the classname: from "Class cWebSessionManagerStandard is a cWebSessionManager" to "Class cWebSessionManager{''YourSystemName''} is a cWebSessionManagerStandard" (so sub-classing cWebSessionManagerStandard)
#Change the user data dictionary instance: in the '''Construct_Object''' procedure change "Get Create (RefClass(cWebAppUserDataDictionary)) to hoUserDD" to "Get Create (RefClass(c{''YourUserTable''}DataDictionary)) to hoUserDD"
#Modify the '''UserLogin''' function:
##Replace the line: "Move sLoginName to WebAppUser.LoginName" with "Move sLoginName to {''YourUserTable''}.{''YourIdCol''}
##Replace the line: "If (Found and (Lowercase(sLoginName) = Lowercase(Trim(WebAppUser.LoginName)))) Begin" with "If (Found and (Lowercase(sLoginName) = Lowercase(Trim({''YourUserTable''}.{''YourIdCol''})))) Begin"
##Replace the line: "Get Field_Current_Value of hoUserDD Field WebAppUser.Password to sUserPassword" with "Get Field_Current_Value of hoUserDD Field {''YourUserTable''}.{''YourPasswordCol''} to sUserPassword"
##Replace the line: "Set Field_Changed_Value of hoUserDD Field WebAppUser.LastLogin to (CurrentDateTime())" with "Set Field_Changed_Value of hoUserDD Field {''YourUserTable''}.{''YourLastLoginCol''} to (CurrentDateTime())" // This one is optional. You may not have such a column (a date, by default) and if you do not wish to create one just remove the line
#Modify the '''UpdateSessionProperties''' function:
##Replace the line "Set psUsername to (Trim(WebAppUser.FullName))" with "Set psUsername to (Trim({''YourUserTable''}.{''YourUserFullname''}))" // Optional - otherwise just remove the line
##Replace the line "Set psLoginName to (Trim(WebAppUser.LoginName))" with "Set psLoginName to (Trim({''YourUserTable''}.{''YourIdColumn''}))
##Replace the line: "Set piUserRights to WebAppUser.Rights" with "Set piUserRights to {''YourUserTable''}.{''YourRightsColumn''} // Optional - if you don't have a rights column, remove the line. Note: if you use an ASCII column, rather than a numeric one for this, you will need to add a different property in the Construct_Object procedure of the class - something like "Property String psUserType" and "Set" that instead
#Remove all the other methods from your sub-class (they are covered in cWebSessionManagerStandard) :
##CreateSession
##ValidateSession
##IsLoggedIn
##ComparePasswords
##OnSessionPropertiesSet
##OnSessionPropertiesClear
##EndSession

====Step 5. Modify SessionManager.wo to use your sub-class:====

#Change: "Use cWebSessionManagerStandard.pkg" to "Use cWebSessionManager{''YourSystemName''}.pkg"
#Change: "Object oSessionManager is a cWebSessionManagerStandard" to "Object oSessionManager is a cWebSessionManager{''YourSystemName''}"

Now you should be good to go and users of your Windows app will/can also be users of your WebApp!

Using your own user table in WebApps

2021-04-30T13:16:46Z

Mikepeat: Creating

In most cases when creating a WebApp for an existing (Windows) system, that system will already have a mechanism for checking user credentials (i.e. user-name and password) in existance. The Data Access supplied mechanism for WebApps uses its own tables for this and for session management within that. So how do we integrate the two?

Actually it is reasonably simple, but I'm going to go through it line-by-line, so it will seem like a lot, but it really isn't.

The instructions below assume that your system has a user table; that it has a userID column of some sort; that column is the primary (unique) key; and that column is the sole element of Index.1 on that table. (If that last is not the case, you will have to also modify the "Send Find of hoUserDD EQ Index.1" line in the Userlogin procedure in your sub-class to use the correct index.)

Text in {''italics''} should be replaced with the appropriate values for your own system.

====Step 1. If you have not already done it, Create a WebApp Project in your workspace.====

====Step 2. From {''DataFlexInstalledLocation''}\Pkg:====

# Copy cWebSessionManagerStandard.pkg (note: not cWebSessionManager.pkg) to your AppSrc directory, renaming it to cWebSessionManager{''YourSystemName''}.pkg
# Copy cWebAppUserDataDictionary.pkg and cWebAppSessionDataDictionary.pkg to your DDSrc directory (the former will not actually be used, but will be modified by the next step of the process, so best to copy it too)

====Step 3. Change the relationship of WebAppSession to WebAppUser to point to your user table instead:====

#The relationship needs to be on identically defined columns (same type and size). I don't think that we ought to impact the existing system when that can be avoided, so if a change is needed (and it usually will be) the change should be at the WebAppSession table end. Modify (in the Studio, right-click WebAppSession in the Table Explorer pane/tab, select "Edit Table" and make the required change to the LoginName column) that so that it matches the (unique) primary key (the user ID) of your current user table. (So if your current user table has a column - say, UserID - which is ASCII 10, modify WebAppSession.LoginName to be ASCII 10 from its original ASCII 20.)
#In the "Relationships" tab, delete the relationship to WebAppUser (the only one there) and add a replacement pointing to your user table, from LoginName on WebAppSession, to whatever the user ID column is on your user table.

====Step 4. Modify your cWebSessionManager sub-class:====

#Change the use statement: "Use cWebSessionManager.pkg" to "Use cWebSessionManagerStandard.pkg"
#Replace the use statement: replace "Use cWebAppUserDataDictionary.dd" with "Use c{''YourUserTable''}DataDictionary.dd"
#Change the classname: from "Class cWebSessionManagerStandard is a cWebSessionManager" to "Class cWebSessionManager{''YourSystemName''} is a cWebSessionManagerStandard" (so sub-classing cWebSessionManagerStandard)
#Change the user data dictionary instance: in the '''Construct_Object''' procedure change "Get Create (RefClass(cWebAppUserDataDictionary)) to hoUserDD" to "Get Create (RefClass(c{''YourUserTable''}DataDictionary)) to hoUserDD"
#Modify the '''UserLogin''' function:
##Replace the line: "Move sLoginName to WebAppUser.LoginName" with "Move sLoginName to {''YourUserTable''}.{''YourIdCol''}
##Replace the line: "If (Found and (Lowercase(sLoginName) = Lowercase(Trim(WebAppUser.LoginName)))) Begin" with "If (Found and (Lowercase(sLoginName) = Lowercase(Trim({''YourUserTable''}.{''YourIdCol''})))) Begin"
##Replace the line: "Get Field_Current_Value of hoUserDD Field WebAppUser.Password to sUserPassword" with "Get Field_Current_Value of hoUserDD Field {''YourUserTable''}.{''YourPasswordCol''} to sUserPassword"
##Replace the line: "Set Field_Changed_Value of hoUserDD Field WebAppUser.LastLogin to (CurrentDateTime())" with "Set Field_Changed_Value of hoUserDD Field {''YourUserTable''}.{''YourLastLoginCol''} to (CurrentDateTime())" // This one is optional. You may not have such a column (a date, by default) and if you do not wish to create one just remove the line
#Modify the '''UpdateSessionProperties''' function:
##Replace the line "Set psUsername to (Trim(WebAppUser.FullName))" with "Set psUsername to (Trim({''YourUserTable''}.{''YourUserFullname''}))" // Optional - otherwise just remove the line
##Replace the line "Set psLoginName to (Trim(WebAppUser.LoginName))" with "Set psLoginName to (Trim({''YourUserTable''}.{''YourIdColumn''}))
##Replace the line: "Set piUserRights to WebAppUser.Rights" with "Set piUserRights to {''YourUserTable''}.{''YourRightColumn''} // Optional - if you don't have a rights column, remove the line. Note: if you use an ASCII column, rather than a numeric one for this, you will need to add a different property in the Construct_Object procedure of the class - something like "Property String psUserType" and "Set" that instead
#Remove all the other methods from your sub-class (they are covered in cWebSessionManagerStandard) :
##CreateSession
##ValidateSession
##IsLoggedIn
##ComparePasswords
##OnSessionPropertiesSet
##OnSessionPropertiesClear
##EndSession

====Step 5. Modify SessionManager.wo to use your sub-class:====

#Change: "Use cWebSessionManagerStandard.pkg" to "Use cWebSessionManager{''YourSystemName''}.pkg"
#Change: "Object oSessionManager is a cWebSessionManagerStandard" to "Object oSessionManager is a cWebSessionManager{''YourSystemName''}"

Now you should be good to go and users of your Windows app will/can also be users of your WebApp!

Read and write files example

2021-02-22T14:04:41Z

Mikepeat: Added link to blog

==Listing for the "Read and write files example" view:==

(From the Unicorn blog post: [https://www.unicorninterglobal.com/company/blog/working-with-binary-files-in-dataflex Working with binary files in DataFlex])

<source lang="vdf">
Use Windows.pkg
Use DFClient.pkg
Use cCharTranslate.pkg
Use seq_chnl.pkg
Use File_dlg.pkg
Use cTextEdit.pkg

Deferred_View Activate_oReadWriteFiles for ;
Object oReadWriteFiles is a dbView

Set Border_Style to Border_Thick
Set Size to 155 533
Set Location to 1 2
Set Label to "Read and write files example"

Property String psMyFile
Property Integer piOldSize

// This is what provides the means to encode/decode base64:
Object oTrans is a cCharTranslate
End_Object

// These two functions - ReadMyFile and WriteMyFile - are where the work
// gets done.

Function ReadMyFile String sFilePathName Returns Boolean
Integer iChn
UChar[] ucaData
String sFile
Boolean bExists

// For timing test
DateTime dtStart dtEnd
Timespan tsDiff

// Check file exists
File_Exist sFilePathName bExists

If not bExists Begin
Send UserError ('File "' + sFilePathName + '" was not found') "File not found"
Function_Return False
End

Get Seq_New_Channel to iChn
Direct_Input channel iChn ("Binary:" + sFilePathName)

If not (SeqEof) Begin

// Timing test
Move (CurrentDateTime()) to dtStart

Read_Block channel iChn ucaData -1
Move (Base64EncodeUCharArray(oTrans(Self), ucaData)) to ucaData
Set_Argument_Size (SizeOfArray(ucaData) + 1)
Move (UCharArrayToString(ucaData)) to sFile

// Timeing test
Move (CurrentDateTime()) to dtEnd
Move (dtEnd - dtStart) to tsDiff
// Showln ("Read: " * String(SpanTotalMilliseconds(tsDiff)) + "ms")
End
Else Begin
Send UserError ('File "' + sFilePathName + '" does not exist or was empty') "File Error"
Function_Return False
End

Close_Output channel iChn
Send Seq_Release_Channel iChn
Set psMyFile to sFile

Function_Return True
End_Function

Function WriteMyFile String sFilePathName Returns Boolean
Integer iChn iPos iResp
UChar[] ucaFile
String sPath sDir sFile
Boolean bExists

// For timing test
DateTime dtStart dtEnd
Timespan tsDiff

Move (RightPos("\", sFilePathName)) to iPos

If not iPos Begin
Send UserError "Could not find folder" "Folder Error"
Function_Return False
End

Move (Left(sFilePathName, (iPos - 1))) to sPath

File_Exist sPath bExists

If not bExists Begin
Send UserError ('Folder "' + sPath + '" does not exist') "Folder Error"
Function_Return False
End

Move (Right(sFilePathName, (Length(sFilePathName) - iPos))) to sFile
File_Exist sFilePathName bExists

If bExists Begin
Move (Right(sFilePathName, (Length(sFilePathName) - iPos))) to sFile
Get YesNo_Box ;
('The file "' + sFile + '" already exists in folder' * sPath + '. Do you wish to overwrite it?') ;
"Overwrite file?" to iResp

If (iResp = MBR_NO) ;
Function_Return False
End

Move (StringToUCharArray(psMyFile(Self))) to ucaFile
Move (Base64DecodeUCharArray(oTrans(Self), ucaFile)) to ucaFile

// If some other program has the file open (and in some cases, has even
// previously had the file open), writing to it may fail, so we catch
// that error in order to deal with it ourselves and return "failure"
// rather "success", resetting it after the write operation, and use the
// ERR global indicator to detect the problem.
Send Ignore_Error of Error_Object_Id 32
Move False to Err

// Timing test
Move (CurrentDateTime()) to dtStart

Get Seq_New_Channel to iChn
Direct_Output channel iChn ("Binary:" + sFilePathName)
Write channel iChn ucaFile
Close_Output channel iChn
Send Seq_Release_Channel iChn
Send Trap_Error of Error_Object_Id 32

// Timing test
Move (CurrentDateTime()) to dtEnd
Move (dtEnd - dtStart) to tsDiff
// Showln ("Write:" * String(SpanTotalMilliseconds(tsDiff)) + "ms")

If (Err) Begin
Send UserError ('There was an error writing to file "' + sFilePathName + '"') "Write Error"
Function_Return False
End

Function_Return True
End_Function

// The user interface...

Object oOpenDialog is a OpenDialog
End_Object

Object oSaveAsDialog is a SaveAsDialog
End_Object

Object oRead is a Form
Set Size to 13 390
Set Location to 3 86
Set Label to "File path-name to read:"
Set psToolTip to "File path-name to read"
Set Label_Justification_Mode to JMode_Right
Set Label_Col_Offset to 2
Set Value to ;
"C:\Program Files (x86)\DataFlex 19.1\Documentation\Installation_and_Environment_Guide.pdf"
Set Prompt_Button_Mode to PB_PromptOn
Set peAnchors to anTopLeftRight

Procedure Prompt
Boolean bOK
String sFile

Get Show_Dialog of oOpenDialog to bOK

If bOK Begin
Get File_Name of oOpenDialog to sFile
Set Value to sFile
End

End_Procedure

End_Object

Object oDoRead is a Button
Set Size to 14 47
Set Location to 3 480
Set Label to "Read file"
Set peAnchors to anTopRight

Procedure OnClick
String sFile
Boolean bOK
Integer iOldSize iNewSize

Get_Argument_Size to iOldSize
Set piOldSize to iOldSize
Set Value of oBase64File to ""

Get Value of oRead to sFile
Get ReadMyFile sFile to bOK

Set Enabled_State of oWrite to bOK
Set Enabled_State of oDoWrite to bOK

If bOK Begin
Get_Argument_Size to iNewSize
Set piMaxChars of oBase64File to iNewSize
Set Value of oBase64File to (If(bOK, psMyFile(Self), ""))
End
Else Begin
Set_Argument_Size (piOldSize(Self))
Set piMaxChars of oBase64File to (piOldSize(Self))
End

Send Info_Box ('File "' + sFile + ;
If(bOK, '" was read successfully', '" could not be read')) ;
(If(bOK, "Success", "Failure"))
End_Procedure

End_Object

Object oWrite is a Form
Set Size to 13 390
Set Location to 20 86
Set Label to "File path-name to write:"
Set Label_Justification_Mode to JMode_Right
Set Label_Col_Offset to 2
Set Enabled_State to False
Set Value to "C:\Temp\MyTestFile.pdf"
Set Prompt_Button_Mode to PB_PromptOn
Set peAnchors to anTopLeftRight

Procedure Prompt
Boolean bOK
String sFile

Get Show_Dialog of oSaveAsDialog to bOK

If bOK Begin
Get File_Name of oSaveAsDialog to sFile
Set Value to sFile
End

End_Procedure

End_Object

Object oDoWrite is a Button
Set Size to 14 47
Set Location to 20 480
Set Label to "Write file"
Set Enabled_State to False
Set peAnchors to anTopRight

Procedure OnClick
String sFile
Boolean bOK

Get Value of oWrite to sFile

If (sFile = "") Begin
Send Info_Box "You must enter a file path and name to write to" "Enter Filepath"
Procedure_Return
End

Get WriteMyFile sFile to bOK

Set Enabled_State of oWrite to (not(bOK))
Set Enabled_State of oDoWrite to (not(bOK))

If bOK Begin
Set Value of oBase64File to ""
Set psMyFile to ""
Set_Argument_Size (piOldSize(Self))
Set piMaxChars of oBase64File to (piOldSize(Self))
End

Send Info_Box ('File "' + sFile + ;
If(bOK, '" was written successfully', '" was not written')) ;
(If(bOK, "Success", "Failure"))
End_Procedure

End_Object

Object oBase64File is a cTextEdit
Set Size to 101 520
Set Location to 46 6
Set Read_Only_State to True
Set Label to "Base64 Encoded File (will be gibberish... unless vous parlez base64!):"
Set peAnchors to anAll
End_Object

CD_End_Object

</source>

Read and write files example

2021-02-18T07:59:06Z

Mikepeat: Creating

==Listing for the "Read and write files example" view:==

<source lang="vdf">
Use Windows.pkg
Use DFClient.pkg
Use cCharTranslate.pkg
Use seq_chnl.pkg
Use File_dlg.pkg
Use cTextEdit.pkg

Deferred_View Activate_oReadWriteFiles for ;
Object oReadWriteFiles is a dbView

Set Border_Style to Border_Thick
Set Size to 155 533
Set Location to 1 2
Set Label to "Read and write files example"

Property String psMyFile
Property Integer piOldSize

// This is what provides the means to encode/decode base64:
Object oTrans is a cCharTranslate
End_Object

// These two functions - ReadMyFile and WriteMyFile - are where the work
// gets done.

Function ReadMyFile String sFilePathName Returns Boolean
Integer iChn
UChar[] ucaData
String sFile
Boolean bExists

// For timing test
DateTime dtStart dtEnd
Timespan tsDiff

// Check file exists
File_Exist sFilePathName bExists

If not bExists Begin
Send UserError ('File "' + sFilePathName + '" was not found') "File not found"
Function_Return False
End

Get Seq_New_Channel to iChn
Direct_Input channel iChn ("Binary:" + sFilePathName)

If not (SeqEof) Begin

// Timing test
Move (CurrentDateTime()) to dtStart

Read_Block channel iChn ucaData -1
Move (Base64EncodeUCharArray(oTrans(Self), ucaData)) to ucaData
Set_Argument_Size (SizeOfArray(ucaData) + 1)
Move (UCharArrayToString(ucaData)) to sFile

// Timeing test
Move (CurrentDateTime()) to dtEnd
Move (dtEnd - dtStart) to tsDiff
// Showln ("Read: " * String(SpanTotalMilliseconds(tsDiff)) + "ms")
End
Else Begin
Send UserError ('File "' + sFilePathName + '" does not exist or was empty') "File Error"
Function_Return False
End

Close_Output channel iChn
Send Seq_Release_Channel iChn
Set psMyFile to sFile

Function_Return True
End_Function

Function WriteMyFile String sFilePathName Returns Boolean
Integer iChn iPos iResp
UChar[] ucaFile
String sPath sDir sFile
Boolean bExists

// For timing test
DateTime dtStart dtEnd
Timespan tsDiff

Move (RightPos("\", sFilePathName)) to iPos

If not iPos Begin
Send UserError "Could not find folder" "Folder Error"
Function_Return False
End

Move (Left(sFilePathName, (iPos - 1))) to sPath

File_Exist sPath bExists

If not bExists Begin
Send UserError ('Folder "' + sPath + '" does not exist') "Folder Error"
Function_Return False
End

Move (Right(sFilePathName, (Length(sFilePathName) - iPos))) to sFile
File_Exist sFilePathName bExists

If bExists Begin
Move (Right(sFilePathName, (Length(sFilePathName) - iPos))) to sFile
Get YesNo_Box ;
('The file "' + sFile + '" already exists in folder' * sPath + '. Do you wish to overwrite it?') ;
"Overwrite file?" to iResp

If (iResp = MBR_NO) ;
Function_Return False
End

Move (StringToUCharArray(psMyFile(Self))) to ucaFile
Move (Base64DecodeUCharArray(oTrans(Self), ucaFile)) to ucaFile

// If some other program has the file open (and in some cases, has even
// previously had the file open), writing to it may fail, so we catch
// that error in order to deal with it ourselves and return "failure"
// rather "success", resetting it after the write operation, and use the
// ERR global indicator to detect the problem.
Send Ignore_Error of Error_Object_Id 32
Move False to Err

// Timing test
Move (CurrentDateTime()) to dtStart

Get Seq_New_Channel to iChn
Direct_Output channel iChn ("Binary:" + sFilePathName)
Write channel iChn ucaFile
Close_Output channel iChn
Send Seq_Release_Channel iChn
Send Trap_Error of Error_Object_Id 32

// Timing test
Move (CurrentDateTime()) to dtEnd
Move (dtEnd - dtStart) to tsDiff
// Showln ("Write:" * String(SpanTotalMilliseconds(tsDiff)) + "ms")

If (Err) Begin
Send UserError ('There was an error writing to file "' + sFilePathName + '"') "Write Error"
Function_Return False
End

Function_Return True
End_Function

// The user interface...

Object oOpenDialog is a OpenDialog
End_Object

Object oSaveAsDialog is a SaveAsDialog
End_Object

Object oRead is a Form
Set Size to 13 390
Set Location to 3 86
Set Label to "File path-name to read:"
Set psToolTip to "File path-name to read"
Set Label_Justification_Mode to JMode_Right
Set Label_Col_Offset to 2
Set Value to ;
"C:\Program Files (x86)\DataFlex 19.1\Documentation\Installation_and_Environment_Guide.pdf"
Set Prompt_Button_Mode to PB_PromptOn
Set peAnchors to anTopLeftRight

Procedure Prompt
Boolean bOK
String sFile

Get Show_Dialog of oOpenDialog to bOK

If bOK Begin
Get File_Name of oOpenDialog to sFile
Set Value to sFile
End

End_Procedure

End_Object

Object oDoRead is a Button
Set Size to 14 47
Set Location to 3 480
Set Label to "Read file"
Set peAnchors to anTopRight

Procedure OnClick
String sFile
Boolean bOK
Integer iOldSize iNewSize

Get_Argument_Size to iOldSize
Set piOldSize to iOldSize
Set Value of oBase64File to ""

Get Value of oRead to sFile
Get ReadMyFile sFile to bOK

Set Enabled_State of oWrite to bOK
Set Enabled_State of oDoWrite to bOK

If bOK Begin
Get_Argument_Size to iNewSize
Set piMaxChars of oBase64File to iNewSize
Set Value of oBase64File to (If(bOK, psMyFile(Self), ""))
End
Else Begin
Set_Argument_Size (piOldSize(Self))
Set piMaxChars of oBase64File to (piOldSize(Self))
End

Send Info_Box ('File "' + sFile + ;
If(bOK, '" was read successfully', '" could not be read')) ;
(If(bOK, "Success", "Failure"))
End_Procedure

End_Object

Object oWrite is a Form
Set Size to 13 390
Set Location to 20 86
Set Label to "File path-name to write:"
Set Label_Justification_Mode to JMode_Right
Set Label_Col_Offset to 2
Set Enabled_State to False
Set Value to "C:\Temp\MyTestFile.pdf"
Set Prompt_Button_Mode to PB_PromptOn
Set peAnchors to anTopLeftRight

Procedure Prompt
Boolean bOK
String sFile

Get Show_Dialog of oSaveAsDialog to bOK

If bOK Begin
Get File_Name of oSaveAsDialog to sFile
Set Value to sFile
End

End_Procedure

End_Object

Object oDoWrite is a Button
Set Size to 14 47
Set Location to 20 480
Set Label to "Write file"
Set Enabled_State to False
Set peAnchors to anTopRight

Procedure OnClick
String sFile
Boolean bOK

Get Value of oWrite to sFile

If (sFile = "") Begin
Send Info_Box "You must enter a file path and name to write to" "Enter Filepath"
Procedure_Return
End

Get WriteMyFile sFile to bOK

Set Enabled_State of oWrite to (not(bOK))
Set Enabled_State of oDoWrite to (not(bOK))

If bOK Begin
Set Value of oBase64File to ""
Set psMyFile to ""
Set_Argument_Size (piOldSize(Self))
Set piMaxChars of oBase64File to (piOldSize(Self))
End

Send Info_Box ('File "' + sFile + ;
If(bOK, '" was written successfully', '" was not written')) ;
(If(bOK, "Success", "Failure"))
End_Procedure

End_Object

Object oBase64File is a cTextEdit
Set Size to 101 520
Set Location to 46 6
Set Read_Only_State to True
Set Label to "Base64 Encoded File (will be gibberish... unless vous parlez base64!):"
Set peAnchors to anAll
End_Object

CD_End_Object

</source>

UK DataFlex Group

2020-07-08T09:14:52Z

Mikepeat: Added mail link

The UK DataFlex Group started in October 2018, to bring together people who manage and develop DataFlex software in the UK. Of course, DataFlexers from further afield are welcome!

Generally this group aims to have informal, one day events covering just a few main topics, with focus on finding out more about what each other are working on and how the group can work together to help each other.

A summary of each event, with relevant links to presentations etc. will be listed on this page.

==Events==

===9th July 2020===
Zoom meetup

Time: Jul 9, 2020 07:00 PM London (This is 2:00PM EST)

This will be our first 'virtual' meetup using Zoom. The advantage of this being a Zoom meetup, rather than our usual UK based meetups, is that anyone can join.

'''How to join the Zoom meetup'''

If you would like to attend the meetup, but have not received an email invitation, containing the meeting link and sign in details (only sent to the opted in, UK group), please email [mailto:info@unicorninterglobal.com info@unicorninterglobal.com] and we will email you the meeting details.

Please add any suggestions or things you would like to be discussed below this point.

Looking forward to seeing you all there.

----

===13th May 2020 - Cancelled ===
[https://www.kingshoteluk.com/ King's Hotel], Oxford Rd, Stokenchurch, High Wycombe HP14 3TA '''

See the date, location and agenda from the link below.

[https://www.unicorninterglobal.com/news/uk-dataflex-meetup-13th-may-2020 May 2020 UK DataFlex Group meetup]

Sadly this event was cancelled due to COVID-19. As soon as it is safe for everyone, we will arrange the next meetup.

----

===2nd October 2019===
[https://www.eynshamhall.com/ Eynsham Hall Hotel & Spa], Witney, Oxfordshire, OX29 6PN '''

See the date, location and agenda from the link below.

[https://www.unicorninterglobal.com/news/2019/uk-dataflex-meetup-2nd-october-2019 October 2019 UK DataFlex Group meetup]

Summary of the day:

* Harm Wibier from Data Access Europe gave a DataFlex NextGen presentation, covering 64-bit and Unicode. Note, you can find out more or contribute to this subject on the page [[Make your applications work in DataFlex NextGen]].

* Next up, David Knowles from DonorFlex gave an informative presentation on how he has used [https://www.dataaccess.eu/products/dataflex-reports-245 DataFlex Reports] to significantly reduce the number of Crystal Reports that they were previously using.

* Harm then gave an overview of how to cleanup your code for DataFlex 19.1. This is an optional process and is mostly handled through a new compiler warning system. Your existing applications will continue to run the same, but you may need to make a few changes. You can read more about code cleanup in the [https://docs.dataaccess.com/dataflexhelp/#t=mergedProjects/Welcome/Language_and_Code_Cleanup.htm DataFlex Help - Language and Code Cleanup]

* Peter Bragg showed us how DonorFlex developed a new Web application based on their extensive DonorFlex Windows application. It was very interesting to see how the Web app that Peter demoed was using virtually out of the box settings.

* Mike Peat talked about MySQL, DataFlex, MariaDB and Aurora and gave some price and speed comparisons for them, then demonstrated setting up an [https://aws.amazon.com/rds/aurora/ Amazon RDS Aurora] database and converted the DataFlex WebOrder sample to it. This presentation was based on the Synergy 2019 presentation 'MySQL and More for DataFlex'. You can view the slides from the [https://synergy.dataaccess.com/index.php/presentations-2/ Synergy 2019 presentations page].

* Lastly, we rounded up with a general question and answer session - always useful to hear other people's suggestions and solutions to your own problems!

The date for the next UK DataFlex Group meetup was set for the 13th May 2020.

----

===1st May 2019===
[https://www.eynshamhall.com/ Eynsham Hall Hotel & Spa], Witney, Oxfordshire, OX29 6PN '''

See the date, location and agenda from the link below.

[https://www.unicorninterglobal.com/news/2019/uk-dataflex-meetup-1st-may-2019 May 2019 UK DataFlex Group meetup]

A quick summary of the day:

* Hilton Gray gave us an overview of Clubwise's business, their current technology stack and where they were going with it, followed by discussions prompted by that.

* Wil van Antwerpen gave a presentation on [https://projects.vdf-guidance.com/projects/hammer The Hammer].

* We had a bit of discussion about how we would like the group to continue: we all liked the venue (Eynsham Hall Hotel), so decided to meet there again on Wednesday 2nd October.

* Simon Gottschalk gave a presentation on how his Shipping Vessel Registration system used Sencha's ExtJS as a front-end to his back-end DataFlex system, the current DA web/JS framework not having been available when he started developing it.

* After lunch Wil moved on to presenting [https://projects.vdf-guidance.com/projects/dfrefactor DFRefactor].

* Hilton gave us an in-depth view of Clubwise's agile, Scrum-based development processes (prompted by a question about his role at Clubwise).

* Finally Graham MacWhirter outlined Select's business and development challenges and a look at where they were going with WebApp, which also prompted various discussions until we ran out of time.

----

===30th October 2018===
Bromsgrove Hotel & Spa, Birmingham'''

Peter Bragg from CMAC Computer System Ltd. demonstrated [https://www.donorflex.com/ donorflex] their fundraising and CRM product, which it quickly became apparent from the extensive detail in the system, is sooo much more than 'just' a CRM system.

Next up, Mike Peat gave a [https://docs.google.com/presentation/d/1nuG_19IQL1cHROxTJSmFEQJg6xrsVYE9fEbObvW7Nzk/edit#slide=id.g378e3ad6e3_1_44 Creating RESTful JSON Web Services with DataFlex 19.1 presentation]. You can find the earlier version of this presentation for DF 19.0 [https://www.unicorninterglobal.com/Company-Presentations-RESTful-JSON-Web-Services-880 here].

Finally, Nick Nikijuluw from Data Access Europe, shared what's coming down the track for DataFlex, no promises, but a welcome insight to what could be in the pipeline.

[[Category:JSON]]
[[Category:DataFlex Community]]
[[Category:Events]]

DfSplat

2020-07-08T09:13:04Z

Mikepeat: Spelling

'''dfSPlat''' is a free open source third party tool, intended to help with debugging DataFlex applications. It is written in DataFlex and wraps the DataFlex development components in order to run. At this moment it can be used to debug applications from Visual DataFlex 12.0 up to DataFlex 19.1

==Notes==
*This tool is currently (March 2020) in alpha stage.

==Articles==
* [[Using dfSplat to identify object leaks]]

==External Links==
*[https://projects.vdf-guidance.com/projects/dfsplat dfSplat homepage]
*[https://projects.vdf-guidance.com/projects/dfsplat/files dfSplat downloads]

[[Category: Development Tools]]

File:ProcPoolDemo.zip

2020-06-15T13:20:26Z

Mikepeat: Mikepeat uploaded a new version of File:ProcPoolDemo.zip

Process Pool Demo

2020-06-15T13:19:59Z

Mikepeat: Remove commented-out code

In an [https://www.unicorninterglobal.com/company/blog/dataflex-webapp-process-pooling-demo article] on the [https://www.unicorninterglobal.com Unicorn InterGlobal web site] I describe my Process Pooling Demo web view.

The code for it is as follows and you can download the zip file from this link: [[File:ProcPoolDemo.zip]].

(Note: now modified to work with DataFlex 20.0 as well as DataFlex 19.1... and possibly prior versions as well - no guarantees though. I have only tested with 19.1 and 20.0.)

<source lang="dataflex">
Use cWebView.pkg
Use cWebModalDialog.pkg
Use cWebPanel.pkg
Use cWebGroup.pkg
Use cWebForm.pkg
Use cWebButton.pkg
Use cWebSpacer.pkg
Use cWebList.pkg
Use cWebColumn.pkg
Use cWebLabel.pkg
Use cRegistry.pkg
Use Flexml.pkg

Define PROCESS_VM_READ for |CI$0010
Define PROCESS_QUERY_INFORMATION for |CI$0400

Define KEY_WOW64_64KEY for |CI$0100

// Wrap all these in #IFNDEF/#ENDIF blocks to avoid any conflicts
// with the same things already defined in the application

#IFNDEF get_GetLastError
External_Function GetLastError "GetLastError" Kernal32.DLL Returns DWord
#ENDIF

#IFNDEF get_GetCurrentProcessId
External_Function GetCurrentProcessId "GetCurrentProcessId" Kernel32.Dll Returns Integer
#ENDIF

#IFNDEF get_EnumProcesses
External_Function EnumProcesses "K32EnumProcesses" Kernel32.DLL ;
Pointer lpidProcess ;
DWord cb ;
Pointer lpcbNeeded ;
Returns Integer
#ENDIF

#IFNDEF get_OpenProcess
External_Function OpenProcess "OpenProcess" Kernel32.Dll ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessId ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessHandle
External_Function ProcessHandle "OpenProcess" Kernel32.DLL ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessID ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessImageFileName
External_Function ProcessImageFileName "K32GetProcessImageFileNameA" Kernel32.DLL ;
Handle hProcess ;
Pointer lpImageFileName ;
DWord nSize ;
Returns DWord
#ENDIF

#IFNDEF _struct_stAllMyState
// Struct to hold state
Struct stAllMyState
Time tmClicked
String sFirstAswer
Time tmAnswered1
String SecondAnswer
Time tmAnswered2
Integer iProc1
Integer iProc2
Integer iProc3
End_Struct
#ENDIF

#IFNDEF C_CRLF
// Just for formatting the result of the Yes/No cascade in this case:
Define C_CRLF for (Character(13) + Character(10))
#ENDIF

// The following items will (almost always) have different values in
// different processes in the WebApp process pool, but will remain static
// in any given process.

Global_Variable Integer giRandom
Move (Random(10000)) to giRandom

// This will be a property of oWabApp:
Property Integer piRandom (Random(10000) + 10000)

// Will be opened in the WebApp
Open Flexerrs
Clear Flexerrs
Move (Random(99) + 1) to Flexerrs.Recnum
Find EQ FlexErrs by Recnum

//==============================================================================
// This is a Modal Dialog which will be called from the View,
// included directly in-line here for simplicity:
//==============================================================================
Object oTestDialog is a cWebModalDialog
Set psCaption to "Test Dialog"
Set piMinWidth to 300
Set piMinHeight to 200
Set pbServerOnEscape to False // The only way out
Set pbShowClose to False // is to click "OK"
Set pbServerOnSubmit to True // enable the OnSubmit event

Object oMainPanel is a cWebPanel
Set piColumnCount to 12

Object oProcess is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "This Process ID:"
Set piLabelOffset to 210
End_Object

Object oCaller is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Called from Process ID:"
Set piLabelOffset to 210
End_Object

Object oGlobal is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Global variable giRandom was:"
Set piLabelOffset to 210
End_Object

Object oRegProp is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Regular property piRandom was:"
Set piLabelOffset to 210
End_Object

End_Object

Object oBottomPanel is a cWebPanel
Set piColumnCount to 4
Set peRegion to prBottom

Object oOkButton is a cWebButton
Set psCaption to C_$OK
Set piColumnSpan to 1
Set piColumnIndex to 3

Procedure OnClick
Send Ok
End_Procedure

End_Object

End_Object

Procedure OnSubmit
Send Ok
End_Procedure

Procedure PopupTheDialog Handle hReturnObj Integer iCaller
Send Popup hReturnObj

WebSet psValue of oProcess to (GetCurrentProcessId())
WebSet psValue of oCaller to iCaller
WebSet psValue of oGlobal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
End_Procedure

Function DialogResult Returns String
String sResult

WebGet psValue of oProcess to sResult
Function_Return sResult
End_Function

End_Object

//==============================================================================
// This is the actual view
//==============================================================================
Object oProcPoolDemo is a cWebView
Set piWidth to 700
Set psCaption to "Process Pooling Effects Demo"
Set pbServerOnShow to True

Property Integer[] paiWebAppProcs

// Display this view at start up:
Delegate Set phoDefaultView to Self

// Work out the web application name from the web.config
// file in AppHTML, which we read into an XML object
Function WebAppName Returns String
Handle hoXml hoElem
String sName
Boolean bOK

Get Create (RefClass(cXMLDOMDocument)) to hoXml
Set psDocumentName of hoXml to ;
(psAppHtmlPath(phoWorkspace(ghoApplication)) + "\web.config")
Get LoadXMLDocument of hoXml to bOK
Get FindNode of hoXml "configuration/location/system.webServer/dataflexHttpModule" to hoElem
Get AttributeValue of hoElem "application" to sName
Send Destroy of hoElem
Send Destroy of hoXml
Function_Return sName
End_Function

// Will be set to return value of above function at start-up.
// This is a regular property because the web app name can't
// change while the program is running.
Property String psWebAppName (WebAppName(Self))

// This uses three external functions to find all the processes in the
// current WebApp's process pool - it will get updated on every refresh
// so if you change the number of processes in the pool while the WebApp is
// running you will see it in the view.
//
// It first uses EnumProcesses to find all the running processes on the
// machine.
//
// It then iterates through that list and tries OpenProcess to get a handle
// to it (for some permissions will not allow that, so those are skipped).
//
// Finally it calls ProcessImageFileName to see if that is one of the
// processes running for THIS WebApp. However ProcessImageFileName
// returns a file-path starting with the disk identifer in a slightly odd
// form, i.e. "\DEVICE\HARDDISKVOLUMEn" (n is "1" for my C: drive) and even
// spookier things for mapped drives, so we strip off the "C:\", or whatever,
// from the application file name DataFlex returns and uppercase both, then
// compare THAT to the same length of the right-portion of the image name.
// This may screw up if you have more than one identically pathed web-apps
// on different drives - just so you know. <g>
//
// Note: that although the docs (and the declarations) use DWords,
// on Vincent's advice we are using UIntegers in our code (the same
// thing in reality) because you can use SizeOfType(UInteger) in the
// Watches window when debugging, which you can't for DWord.
Procedure FindWebAppProcs
Integer[] aiWebAppProcs
UInteger[] auiProcs
UInteger uiCb uiNeeded uiSize uiErr
Integer iOK i iLast iPos iSize iPathLen
Handle hProc
UChar[] ucaFile
String sPath sImage

Move (Uppercase(GetApplicationFileName(ghoApplication))) to sPath
// Strip off drive designation:
Move (Pos("\", sPath)) to iPos
Move (Right(sPath, (Length(sPath) - iPos))) to sPath
Move (Length(sPath)) to iPathLen
Move 4096 to iSize

Move (ResizeArray(auiProcs, iSize)) to auiProcs
Move (iSize * SizeOfType(UInteger)) to uiCb
Move 0 to uiNeeded

Move (EnumProcesses(AddressOf(auiProcs), ;
uiCb, ;
AddressOf(uiNeeded))) to iOK

// Just for debugging:
If not iOK ;
Move (GetLastError()) to uiErr

Move (uiNeeded / SizeOfType(UInteger)) to iSize
Move (ResizeArray(auiProcs, iSize)) to auiProcs
Decrement iSize

For i from 0 to iSize
Move (OpenProcess(PROCESS_VM_READ + PROCESS_QUERY_INFORMATION, ;
True, auiProcs[i])) to hProc

If (hProc <> 0) Begin // We DID get a handle to the process
Move (ResizeArray(ucaFile, 0)) to ucaFile
Move (ResizeArray(ucaFile, 2048)) to ucaFile
Move (ProcessImageFileName(hProc, ;
AddressOf(ucaFile), 2048)) to uiSize
Move (ResizeArray(ucaFile, uiSize)) to ucaFile
Move (Uppercase(UCharArrayToString(ucaFile))) to sImage
Move (Right(sImage, iPathLen)) to sImage

If (sImage = sPath) ;
Move auiProcs[i] to aiWebAppProcs[SizeOfArray(aiWebAppProcs)]
End

Loop

Set paiWebAppProcs to aiWebAppProcs
End_Procedure

Procedure OnShow
Send UpdateProcInfo
End_Procedure

// Registry object for getting the WebApp info from the registry:
Object oReg is a cRegistry
Set phRootKey to HKEY_LOCAL_MACHINE
Set pfAccessRights to (KEY_WOW64_64KEY ior KEY_READ)

Function BaseKey Returns String
String[] asParts

Move "SOFTWARE" to asParts[0]
Move "Data Access Worldwide" to asParts[1]
Move "DataFlex" to asParts[2]
Move C_DFVersion to asParts[3]
Move "WebApp Server" to asParts[4]
Move "Web Applications" to asParts[5]

// If it is a 64-bit machine and running on a DF version PRIOR to 20
// Insert "Wow6432Node just after "SOFTWARE":
If (KeyExists(Self, "SOFTWARE\Wow6432Node") and ;
(Number(C_DFVersion) < 20)) ;
Move (InsertInArray(asParts, 1, "Wow6432Node")) to asParts

Function_Return (StrJoinFromArray(asParts, "\"))
End_Function

Function DWKeyValue String sApp String sVal Returns Integer
Boolean bOK
Integer iVal
String sKey

Move (BaseKey(Self) + "\" + sApp) to sKey

Get KeyExists sKey to bOK
If not bOK ;
Function_Return 0

Get OpenKey sKey to bOK
If not bOK ;
Function_Return 0

Move (ReadDWord(Self, sVal)) to iVal
Send CloseKey

Function_Return iVal
End_Function

End_Object

// Refresh all the displayed information
Procedure UpdateProcInfo
String sApp
Integer iMin iMax

Get psWebAppName to sApp
WebSet psValue of oMinProc to (DWKeyValue(oReg(Self), sApp, "MinPool"))
WebSet psValue of oMaxProc to (DWKeyValue(oReg(Self), sApp, "MaxPool"))
WebSet psValue of oCurrProcs to "Unknown"

WebSet psValue of oCurrProcess to (GetCurrentProcessId())
WebSet psValue of oGlobalVal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
WebSet psValue of oDBRec to FlexErrs.Recnum

Send FindWebAppProcs
Send GridRefresh of oProcList
Send Focus of oCallServer
End_Procedure

Object oWebMainPanel is a cWebPanel
Set piColumnCount to 8

Object oExplanation is a cWebLabel
Set piColumnSpan to 0
Set psCaption to ;
('This view demonstrates the fact that in a Process' + ;
' Pooled WebApp (which all modern WebApps generally' + ;
' are) you CANNOT rely on the values in global variables,' + ;
' regular properties and database buffers. They change' + ;
' from one server round-trip to the next. ONLY web' + ;
' properties and Data Dictionary values can be relied on.' + ;
' If you run this under the debugger you will see that' + ;
' only a single process is "in the pool" and the values' + ;
' of the things below do not change, which is why you' + ;
' MUST test Web Apps OUTSIDE the debugger.')
End_Object

Object oProcPoolGrp is a cWebGroup
Set piColumnCount to 8
Set piColumnSpan to 0
Set psCaption to "Process Pool Information:"

Object oPoolInfo is a cWebGroup
Set pbShowBorder to False
Set pbShowCaption to False
Set piColumnCount to 12
Set piColumnSpan to 6

Object oAppName is a cWebForm
Set piColumnSpan to 0
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Web Application:"
Set psValue to (psWebAppName(Self))
End_Object

Object oMinProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Minimum Pool:"
End_Object

Object oMaxProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Maximum Pool:"
End_Object

Object oCurrProcs is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Current Pool:"
End_Object

End_Object

Object oProcList is a cWebList
Set piColumnIndex to 6
Set piColumnSpan to 2
Set pbDataAware to False
Set pbOfflineEditing to True // DON'T call the server on RowChange
// Adjust this to see more/less process numbers without scrolling:
Set piHeight to 200

Object oProcsCol is a cWebColumn
Set psCaption to "Pool Process IDs"
Set piWidth to 100
End_Object

Procedure OnManualLoadData tWebRow[] ByRef aTheRows String ByRef sCurrentRowID
Integer[] aiWebProcs
Integer i iLast iThis

Get paiWebAppProcs of oProcPoolDemo to aiWebProcs
Move (GetCurrentProcessId()) to iThis

Move (SizeOfArray(aiWebProcs)) to iLast
WebSet psValue of oCurrProcs to iLast
Decrement iLast

For i from 0 to iLast
Move aiWebProcs[i] to aTheRows[i].sRowID
Move aiWebProcs[i] to aTheRows[i].aCells[0].sValue

If (aiWebProcs[i] = iThis) Begin
Move aiWebProcs[i] to sCurrentRowID
End

Loop

Forward Send OnManualLoadData (&aTheRows) (&sCurrentRowID)
End_Procedure

End_Object

End_Object

Object oCurrProcess is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Last invoked server process was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oGlobalVal is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Global variable giRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oRegProp is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Regular property piRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oDBRec is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Flexerrs recnum in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oWebValue is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set psLabel to "Your entered value:"
Set psValue to "Hello!"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oNote is a cWebLabel
Set psCaption to "(This is a web property - psValue of oWebValue - so will not change unless YOU change it)"
Set piColumnIndex to 4
Set piColumnSpan to 4
End_Object

Object oButtonSpacer is a cWebSpacer
Set piHeight to 20
End_Object

Object oCallServer is a cWebButton
Set piColumnIndex to 0
Set piColumnSpan to 2
Set psCaption to "Call Server"

Procedure OnClick
Send UpdateProcInfo
End_Procedure

End_Object

Object oInfo is a cWebButton
Set piColumnIndex to 2
Set piColumnSpan to 2
Set psCaption to "Info Box"

Procedure OnClick
Integer iProc

Move (GetCurrentProcessId()) to iProc
Send ShowInfoBox ("InfoBox in process" * String(iProc))
Send UpdateProcInfo
End_Procedure

End_Object

Object oYesNo is a cWebButton
Set piColumnIndex to 4
Set piColumnSpan to 2
Set psCaption to "Yes/No"

// Web Property to hold state between browser/server round-trips
{ WebProperty=Client }
Property stAllMyState ptState

// Is called in response to user's second answer:
Procedure ProcessSecondAnswer Integer eAnswer
stAllMyState tState
String[] asInfo

WebGet ptState to tState
Move (GetCurrentProcessId()) to tState.iProc3
Move (CurrentDateTime()) to tState.tmAnswered2
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.SecondAnswer

// Assemble results:
Move ("You clicked the 'Yes/No' button at" * String(tState.tmClicked) * ;
"in process" * String(tState.iProc1)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your first answer was: '" + ;
tState.sFirstAswer + "' at" * String(tState.tmAnswered1) * ;
"in process" * String(tState.iProc2)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your second answer was: '" + ;
tState.SecondAnswer + "' at" * String(tState.tmAnswered2) * ;
"in process" * String(tState.iProc3)) ;
to asInfo[SizeOfArray(asInfo)]

Send ShowInfoBox (StrJoinFromArray(asInfo, C_CRLF)) "Results"

Send UpdateProcInfo
End_Procedure
WebPublishProcedure ProcessSecondAnswer // Publish the proc to receive control after second answer

// Is called in response to user's first answer:
Procedure ProcessFirstAnswer Integer eAnswer
stAllMyState tState

WebGet ptState to tState

Move (GetCurrentProcessId()) to tState.iProc2
Move (CurrentDateTime()) to tState.tmAnswered1
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.sFirstAswer
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessSecondAnswer)) ;
("Do you REALLY want to do this? (Proc:" * String(tState.iProc2) + ")") ;
"Second question"
End_Procedure
WebPublishProcedure ProcessFirstAnswer // Publish the proc to receive control after first answer

// Triggers the question cascade:
Procedure OnClick
stAllMyState tState

Move (CurrentDateTime()) to tState.tmClicked
Move (GetCurrentProcessId()) to tState.iProc1
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessFirstAnswer)) ;
("Do you want to do this? (Proc:" * String(tState.iProc1) + ")") ;
"First question"
End_Procedure

End_Object

Object oDialog is a cWebButton
Set piColumnIndex to 6
Set piColumnSpan to 2
Set psCaption to "Popup Dialog"

Procedure OnCloseModalDialog Handle hoModalDialog
Integer iProc1 iProc2

If (hoModalDialog = oTestDialog) Begin
Get DialogResult of oTestDialog to iProc1
Move (GetCurrentProcessId()) to iProc2
Send ShowInfoBox ;
("Dialog in process" * String(iProc1) + C_CRLF + ;
"Returned to process" * String(iProc2)) "Result"

Send UpdateProcInfo
End

End_Procedure

Procedure OnClick
Send PopupTheDialog of oTestDialog Self (GetCurrentProcessId())
End_Procedure

End_Object

End_Object

End_Object
</source>

[[Category: Web Applications]]

File:ProcPoolDemo.zip

2020-06-15T13:02:49Z

Mikepeat: Mikepeat uploaded a new version of File:ProcPoolDemo.zip

Process Pool Demo

2020-06-15T13:01:34Z

Mikepeat: Updated for DF v20.0

In an [https://www.unicorninterglobal.com/company/blog/dataflex-webapp-process-pooling-demo article] on the [https://www.unicorninterglobal.com Unicorn InterGlobal web site] I describe my Process Pooling Demo web view.

The code for it is as follows and you can download the zip file from this link: [[File:ProcPoolDemo.zip]].

(Note: now modified to work with DataFlex 20.0 as well as DataFlex 19.1... and possibly prior versions as well - no guarantees though. I have only tested with 19.1 and 20.0.)

<source lang="dataflex">
Use cWebView.pkg
Use cWebModalDialog.pkg
Use cWebPanel.pkg
Use cWebGroup.pkg
Use cWebForm.pkg
Use cWebButton.pkg
Use cWebSpacer.pkg
Use cWebList.pkg
Use cWebColumn.pkg
Use cWebLabel.pkg
Use cRegistry.pkg
Use Flexml.pkg

Define PROCESS_VM_READ for |CI$0010
Define PROCESS_QUERY_INFORMATION for |CI$0400

Define KEY_WOW64_64KEY for |CI$0100

// Wrap all these in #IFNDEF/#ENDIF blocks to avoid any conflicts
// with the same things already defined in the application

#IFNDEF get_GetLastError
External_Function GetLastError "GetLastError" Kernal32.DLL Returns DWord
#ENDIF

#IFNDEF get_GetCurrentProcessId
External_Function GetCurrentProcessId "GetCurrentProcessId" Kernel32.Dll Returns Integer
#ENDIF

#IFNDEF get_EnumProcesses
External_Function EnumProcesses "K32EnumProcesses" Kernel32.DLL ;
Pointer lpidProcess ;
DWord cb ;
Pointer lpcbNeeded ;
Returns Integer
#ENDIF

#IFNDEF get_OpenProcess
External_Function OpenProcess "OpenProcess" Kernel32.Dll ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessId ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessHandle
External_Function ProcessHandle "OpenProcess" Kernel32.DLL ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessID ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessImageFileName
External_Function ProcessImageFileName "K32GetProcessImageFileNameA" Kernel32.DLL ;
Handle hProcess ;
Pointer lpImageFileName ;
DWord nSize ;
Returns DWord
#ENDIF

#IFNDEF _struct_stAllMyState
// Struct to hold state
Struct stAllMyState
Time tmClicked
String sFirstAswer
Time tmAnswered1
String SecondAnswer
Time tmAnswered2
Integer iProc1
Integer iProc2
Integer iProc3
End_Struct
#ENDIF

#IFNDEF C_CRLF
// Just for formatting the result of the Yes/No cascade in this case:
Define C_CRLF for (Character(13) + Character(10))
#ENDIF

// The following items will (almost always) have different values in
// different processes in the WebApp process pool, but will remain static
// in any given process.

Global_Variable Integer giRandom
Move (Random(10000)) to giRandom

// This will be a property of oWabApp:
Property Integer piRandom (Random(10000) + 10000)

// Will be opened in the WebApp
Open Flexerrs
Clear Flexerrs
Move (Random(99) + 1) to Flexerrs.Recnum
Find EQ FlexErrs by Recnum

//==============================================================================
// This is a Modal Dialog which will be called from the View,
// included directly in-line here for simplicity:
//==============================================================================
Object oTestDialog is a cWebModalDialog
Set psCaption to "Test Dialog"
Set piMinWidth to 300
Set piMinHeight to 200
Set pbServerOnEscape to False // The only way out
Set pbShowClose to False // is to click "OK"
Set pbServerOnSubmit to True // enable the OnSubmit event

Object oMainPanel is a cWebPanel
Set piColumnCount to 12

Object oProcess is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "This Process ID:"
Set piLabelOffset to 210
End_Object

Object oCaller is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Called from Process ID:"
Set piLabelOffset to 210
End_Object

Object oGlobal is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Global variable giRandom was:"
Set piLabelOffset to 210
End_Object

Object oRegProp is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Regular property piRandom was:"
Set piLabelOffset to 210
End_Object

End_Object

Object oBottomPanel is a cWebPanel
Set piColumnCount to 4
Set peRegion to prBottom

Object oOkButton is a cWebButton
Set psCaption to C_$OK
Set piColumnSpan to 1
Set piColumnIndex to 3

Procedure OnClick
Send Ok
End_Procedure

End_Object

End_Object

Procedure OnSubmit
Send Ok
End_Procedure

Procedure PopupTheDialog Handle hReturnObj Integer iCaller
Send Popup hReturnObj

WebSet psValue of oProcess to (GetCurrentProcessId())
WebSet psValue of oCaller to iCaller
WebSet psValue of oGlobal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
End_Procedure

Function DialogResult Returns String
String sResult

WebGet psValue of oProcess to sResult
Function_Return sResult
End_Function

End_Object

//==============================================================================
// This is the actual view
//==============================================================================
Object oProcPoolDemo is a cWebView
Set piWidth to 700
Set psCaption to "Process Pooling Effects Demo"
Set pbServerOnShow to True

Property Integer[] paiWebAppProcs

// Display this view at start up:
Delegate Set phoDefaultView to Self

// // Work out the web application name from the WebServiceDispatcher.wo
// // file in AppHTML, which we treat like a .ini file
// Function WebAppName Returns String
// Handle hoIni
// String sName
//
// Get Create (RefClass(cIniFile)) to hoIni
// Set psFileName of hoIni to ;
// (psAppHtmlPath(phoWorkspace(ghoApplication)) + ;
// "\WebServiceDispatcher.wso")
// Get ReadString of hoIni "WebService" "Application" "" to sName
// Send Destroy of hoIni
// Function_Return sName
// End_Function

// Work out the web application name from the web.config
// file in AppHTML, which we read into an XML object
Function WebAppName Returns String
Handle hoXml hoElem
String sName
Boolean bOK

Get Create (RefClass(cXMLDOMDocument)) to hoXml
Set psDocumentName of hoXml to ;
(psAppHtmlPath(phoWorkspace(ghoApplication)) + "\web.config")
Get LoadXMLDocument of hoXml to bOK
Get FindNode of hoXml "configuration/location/system.webServer/dataflexHttpModule" to hoElem
Get AttributeValue of hoElem "application" to sName
Send Destroy of hoElem
Send Destroy of hoXml
Function_Return sName
End_Function

// Will be set to return value of above function at start-up.
// This is a regular property because the web app name can't
// change while the program is running.
Property String psWebAppName (WebAppName(Self))

// This uses three external functions to find all the processes in the
// current WebApp's process pool - it will get updated on every refresh
// so if you change the number of processes in the pool while the WebApp is
// running you will see it in the view.
//
// It first uses EnumProcesses to find all the running processes on the
// machine.
//
// It then iterates through that list and tries OpenProcess to get a handle
// to it (for some permissions will not allow that, so those are skipped).
//
// Finally it calls ProcessImageFileName to see if that is one of the
// processes running for THIS WebApp. However ProcessImageFileName
// returns a file-path starting with the disk identifer in a slightly odd
// form, i.e. "\DEVICE\HARDDISKVOLUMEn" (n is "1" for my C: drive) and even
// spookier things for mapped drives, so we strip off the "C:\", or whatever,
// from the application file name DataFlex returns and uppercase both, then
// compare THAT to the same length of the right-portion of the image name.
// This may screw up if you have more than one identically pathed web-apps
// on different drives - just so you know. <g>
//
// Note: that although the docs (and the declarations) use DWords,
// on Vincent's advice we are using UIntegers in our code (the same
// thing in reality) because you can use SizeOfType(UInteger) in the
// Watches window when debugging, which you can't for DWord.
Procedure FindWebAppProcs
Integer[] aiWebAppProcs
UInteger[] auiProcs
UInteger uiCb uiNeeded uiSize uiErr
Integer iOK i iLast iPos iSize iPathLen
Handle hProc
UChar[] ucaFile
String sPath sImage

Move (Uppercase(GetApplicationFileName(ghoApplication))) to sPath
// Strip off drive designation:
Move (Pos("\", sPath)) to iPos
Move (Right(sPath, (Length(sPath) - iPos))) to sPath
Move (Length(sPath)) to iPathLen
Move 4096 to iSize

Move (ResizeArray(auiProcs, iSize)) to auiProcs
Move (iSize * SizeOfType(UInteger)) to uiCb
Move 0 to uiNeeded

Move (EnumProcesses(AddressOf(auiProcs), ;
uiCb, ;
AddressOf(uiNeeded))) to iOK

// Just for debugging:
If not iOK ;
Move (GetLastError()) to uiErr

Move (uiNeeded / SizeOfType(UInteger)) to iSize
Move (ResizeArray(auiProcs, iSize)) to auiProcs
Decrement iSize

For i from 0 to iSize
Move (OpenProcess(PROCESS_VM_READ + PROCESS_QUERY_INFORMATION, ;
True, auiProcs[i])) to hProc

If (hProc <> 0) Begin // We DID get a handle to the process
Move (ResizeArray(ucaFile, 0)) to ucaFile
Move (ResizeArray(ucaFile, 2048)) to ucaFile
Move (ProcessImageFileName(hProc, ;
AddressOf(ucaFile), 2048)) to uiSize
Move (ResizeArray(ucaFile, uiSize)) to ucaFile
Move (Uppercase(UCharArrayToString(ucaFile))) to sImage
Move (Right(sImage, iPathLen)) to sImage

If (sImage = sPath) ;
Move auiProcs[i] to aiWebAppProcs[SizeOfArray(aiWebAppProcs)]
End

Loop

Set paiWebAppProcs to aiWebAppProcs
End_Procedure

Procedure OnShow
Send UpdateProcInfo
End_Procedure

// Registry object for getting the WebApp info from the registry:
Object oReg is a cRegistry
Set phRootKey to HKEY_LOCAL_MACHINE
Set pfAccessRights to (KEY_WOW64_64KEY ior KEY_READ)

Function BaseKey Returns String
String[] asParts

Move "SOFTWARE" to asParts[0]
Move "Data Access Worldwide" to asParts[1]
Move "DataFlex" to asParts[2]
Move C_DFVersion to asParts[3]
Move "WebApp Server" to asParts[4]
Move "Web Applications" to asParts[5]

// If it is a 64-bit machine and running on a DF version PRIOR to 20
// Insert "Wow6432Node just after "SOFTWARE":
If (KeyExists(Self, "SOFTWARE\Wow6432Node") and ;
(Number(C_DFVersion) < 20)) ;
Move (InsertInArray(asParts, 1, "Wow6432Node")) to asParts

Function_Return (StrJoinFromArray(asParts, "\"))
End_Function

Function DWKeyValue String sApp String sVal Returns Integer
Boolean bOK
Integer iVal
String sKey

Move (BaseKey(Self) + "\" + sApp) to sKey

Get KeyExists sKey to bOK
If not bOK ;
Function_Return 0

Get OpenKey sKey to bOK
If not bOK ;
Function_Return 0

Move (ReadDWord(Self, sVal)) to iVal
Send CloseKey

Function_Return iVal
End_Function

End_Object

// Refresh all the displayed information
Procedure UpdateProcInfo
String sApp
Integer iMin iMax

Get psWebAppName to sApp
WebSet psValue of oMinProc to (DWKeyValue(oReg(Self), sApp, "MinPool"))
WebSet psValue of oMaxProc to (DWKeyValue(oReg(Self), sApp, "MaxPool"))
WebSet psValue of oCurrProcs to "Unknown"

WebSet psValue of oCurrProcess to (GetCurrentProcessId())
WebSet psValue of oGlobalVal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
WebSet psValue of oDBRec to FlexErrs.Recnum

Send FindWebAppProcs
Send GridRefresh of oProcList
Send Focus of oCallServer
End_Procedure

Object oWebMainPanel is a cWebPanel
Set piColumnCount to 8

Object oExplanation is a cWebLabel
Set piColumnSpan to 0
Set psCaption to ;
('This view demonstrates the fact that in a Process' + ;
' Pooled WebApp (which all modern WebApps generally' + ;
' are) you CANNOT rely on the values in global variables,' + ;
' regular properties and database buffers. They change' + ;
' from one server round-trip to the next. ONLY web' + ;
' properties and Data Dictionary values can be relied on.' + ;
' If you run this under the debugger you will see that' + ;
' only a single process is "in the pool" and the values' + ;
' of the things below do not change, which is why you' + ;
' MUST test Web Apps OUTSIDE the debugger.')
End_Object

Object oProcPoolGrp is a cWebGroup
Set piColumnCount to 8
Set piColumnSpan to 0
Set psCaption to "Process Pool Information:"

Object oPoolInfo is a cWebGroup
Set pbShowBorder to False
Set pbShowCaption to False
Set piColumnCount to 12
Set piColumnSpan to 6

Object oAppName is a cWebForm
Set piColumnSpan to 0
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Web Application:"
Set psValue to (psWebAppName(Self))
End_Object

Object oMinProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Minimum Pool:"
End_Object

Object oMaxProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Maximum Pool:"
End_Object

Object oCurrProcs is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Current Pool:"
End_Object

End_Object

Object oProcList is a cWebList
Set piColumnIndex to 6
Set piColumnSpan to 2
Set pbDataAware to False
Set pbOfflineEditing to True // DON'T call the server on RowChange
// Adjust this to see more/less process numbers without scrolling:
Set piHeight to 200

Object oProcsCol is a cWebColumn
Set psCaption to "Pool Process IDs"
Set piWidth to 100
End_Object

Procedure OnManualLoadData tWebRow[] ByRef aTheRows String ByRef sCurrentRowID
Integer[] aiWebProcs
Integer i iLast iThis

Get paiWebAppProcs of oProcPoolDemo to aiWebProcs
Move (GetCurrentProcessId()) to iThis

Move (SizeOfArray(aiWebProcs)) to iLast
WebSet psValue of oCurrProcs to iLast
Decrement iLast

For i from 0 to iLast
Move aiWebProcs[i] to aTheRows[i].sRowID
Move aiWebProcs[i] to aTheRows[i].aCells[0].sValue

If (aiWebProcs[i] = iThis) Begin
Move aiWebProcs[i] to sCurrentRowID
End

Loop

Forward Send OnManualLoadData (&aTheRows) (&sCurrentRowID)
End_Procedure

End_Object

End_Object

Object oCurrProcess is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Last invoked server process was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oGlobalVal is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Global variable giRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oRegProp is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Regular property piRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oDBRec is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Flexerrs recnum in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oWebValue is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set psLabel to "Your entered value:"
Set psValue to "Hello!"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oNote is a cWebLabel
Set psCaption to "(This is a web property - psValue of oWebValue - so will not change unless YOU change it)"
Set piColumnIndex to 4
Set piColumnSpan to 4
End_Object

Object oButtonSpacer is a cWebSpacer
Set piHeight to 20
End_Object

Object oCallServer is a cWebButton
Set piColumnIndex to 0
Set piColumnSpan to 2
Set psCaption to "Call Server"

Procedure OnClick
Send UpdateProcInfo
End_Procedure

End_Object

Object oInfo is a cWebButton
Set piColumnIndex to 2
Set piColumnSpan to 2
Set psCaption to "Info Box"

Procedure OnClick
Integer iProc

Move (GetCurrentProcessId()) to iProc
Send ShowInfoBox ("InfoBox in process" * String(iProc))
Send UpdateProcInfo
End_Procedure

End_Object

Object oYesNo is a cWebButton
Set piColumnIndex to 4
Set piColumnSpan to 2
Set psCaption to "Yes/No"

// Web Property to hold state between browser/server round-trips
{ WebProperty=Client }
Property stAllMyState ptState

// Is called in response to user's second answer:
Procedure ProcessSecondAnswer Integer eAnswer
stAllMyState tState
String[] asInfo

WebGet ptState to tState
Move (GetCurrentProcessId()) to tState.iProc3
Move (CurrentDateTime()) to tState.tmAnswered2
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.SecondAnswer

// Assemble results:
Move ("You clicked the 'Yes/No' button at" * String(tState.tmClicked) * ;
"in process" * String(tState.iProc1)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your first answer was: '" + ;
tState.sFirstAswer + "' at" * String(tState.tmAnswered1) * ;
"in process" * String(tState.iProc2)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your second answer was: '" + ;
tState.SecondAnswer + "' at" * String(tState.tmAnswered2) * ;
"in process" * String(tState.iProc3)) ;
to asInfo[SizeOfArray(asInfo)]

Send ShowInfoBox (StrJoinFromArray(asInfo, C_CRLF)) "Results"

Send UpdateProcInfo
End_Procedure
WebPublishProcedure ProcessSecondAnswer // Publish the proc to receive control after second answer

// Is called in response to user's first answer:
Procedure ProcessFirstAnswer Integer eAnswer
stAllMyState tState

WebGet ptState to tState

Move (GetCurrentProcessId()) to tState.iProc2
Move (CurrentDateTime()) to tState.tmAnswered1
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.sFirstAswer
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessSecondAnswer)) ;
("Do you REALLY want to do this? (Proc:" * String(tState.iProc2) + ")") ;
"Second question"
End_Procedure
WebPublishProcedure ProcessFirstAnswer // Publish the proc to receive control after first answer

// Triggers the question cascade:
Procedure OnClick
stAllMyState tState

Move (CurrentDateTime()) to tState.tmClicked
Move (GetCurrentProcessId()) to tState.iProc1
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessFirstAnswer)) ;
("Do you want to do this? (Proc:" * String(tState.iProc1) + ")") ;
"First question"
End_Procedure

End_Object

Object oDialog is a cWebButton
Set piColumnIndex to 6
Set piColumnSpan to 2
Set psCaption to "Popup Dialog"

Procedure OnCloseModalDialog Handle hoModalDialog
Integer iProc1 iProc2

If (hoModalDialog = oTestDialog) Begin
Get DialogResult of oTestDialog to iProc1
Move (GetCurrentProcessId()) to iProc2
Send ShowInfoBox ;
("Dialog in process" * String(iProc1) + C_CRLF + ;
"Returned to process" * String(iProc2)) "Result"

Send UpdateProcInfo
End

End_Procedure

Procedure OnClick
Send PopupTheDialog of oTestDialog Self (GetCurrentProcessId())
End_Procedure

End_Object

End_Object

End_Object
</source>

[[Category: Web Applications]]

Process Pool Demo

2020-06-12T07:25:18Z

Mikepeat: Changed web property to regular property

In an [https://www.unicorninterglobal.com/company/blog/dataflex-webapp-process-pooling-demo article] on the [https://www.unicorninterglobal.com Unicorn InterGlobal web site] I describe my Process Pooling Demo web view.

The code for it is as follows and you can download the zip file from this link: [[File:ProcPoolDemo.zip]].

<source lang="dataflex">
Use cWebView.pkg
Use cWebModalDialog.pkg
Use cWebPanel.pkg
Use cWebGroup.pkg
Use cWebForm.pkg
Use cWebButton.pkg
Use cWebSpacer.pkg
Use cWebList.pkg
Use cWebLabel.pkg
Use cRegistry.pkg
Use cIniFile.pkg

Define PROCESS_VM_READ for |CI$0010
Define PROCESS_QUERY_INFORMATION for |CI$0400

// Wrap all these in #IFNDEF/#ENDIF blocks to avoid any conflicts
// with the same things already defined in the application

#IFNDEF get_GetLastError
External_Function GetLastError "GetLastError" Kernal32.DLL Returns DWord
#ENDIF

#IFNDEF get_GetCurrentProcessId
External_Function GetCurrentProcessId "GetCurrentProcessId" Kernel32.Dll Returns Integer
#ENDIF

#IFNDEF get_EnumProcesses
External_Function EnumProcesses "K32EnumProcesses" Kernel32.DLL ;
Pointer lpidProcess ;
DWord cb ;
Pointer lpcbNeeded ;
Returns Integer
#ENDIF

#IFNDEF get_OpenProcess
External_Function OpenProcess "OpenProcess" Kernel32.Dll ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessId ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessHandle
External_Function ProcessHandle "OpenProcess" Kernel32.DLL ;
DWord dwDesiredAccess ;
Boolean bInheritHandle ;
DWord dwProcessID ;
Returns Handle
#ENDIF

#IFNDEF get_ProcessImageFileName
External_Function ProcessImageFileName "K32GetProcessImageFileNameA" Kernel32.DLL ;
Handle hProcess ;
Pointer lpImageFileName ;
DWord nSize ;
Returns DWord
#ENDIF

#IFNDEF _struct_stAllMyState
// Struct to hold state
Struct stAllMyState
Time tmClicked
String sFirstAswer
Time tmAnswered1
String SecondAnswer
Time tmAnswered2
Integer iProc1
Integer iProc2
Integer iProc3
End_Struct
#ENDIF

#IFNDEF C_CRLF
// Just for formatting the result of the Yes/No cascade in this case:
Define C_CRLF for (Character(13) + Character(10))
#ENDIF

// The following items will (almost always) have different values in
// different processes in the WebApp process pool, but will remain static
// in any given process.

Global_Variable Integer giRandom
Move (Random(10000)) to giRandom

// This will be a property of oWabApp:
Property Integer piRandom (Random(10000) + 10000)

// Will be opened in the WebApp
Open Flexerrs
Clear Flexerrs
Move (Random(99) + 1) to Flexerrs.Recnum
Find EQ FlexErrs by Recnum

//==============================================================================
// This is a Modal Dialog which will be called from the View,
// included directly in-line here for simplicity:
//==============================================================================
Object oTestDialog is a cWebModalDialog
Set psCaption to "Test Dialog"
Set piMinWidth to 300
Set piMinHeight to 200
Set pbServerOnEscape to False // The only way out
Set pbShowClose to False // is to click "OK"
Set pbServerOnSubmit to True // enable the OnSubmit event

Object oMainPanel is a cWebPanel
Set piColumnCount to 12

Object oProcess is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "This Process ID:"
Set piLabelOffset to 210
End_Object

Object oCaller is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Called from Process ID:"
Set piLabelOffset to 210
End_Object

Object oGlobal is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Global variable giRandom was:"
Set piLabelOffset to 210
End_Object

Object oRegProp is a cWebForm
Set piColumnSpan to 0
Set peLabelAlign to alignRight
Set pbReadOnly to True
Set psLabel to "Regular property piRandom was:"
Set piLabelOffset to 210
End_Object

End_Object

Object oBottomPanel is a cWebPanel
Set piColumnCount to 4
Set peRegion to prBottom

Object oOkButton is a cWebButton
Set psCaption to C_$OK
Set piColumnSpan to 1
Set piColumnIndex to 3

Procedure OnClick
Send Ok
End_Procedure

End_Object

End_Object

Procedure OnSubmit
Send Ok
End_Procedure

Procedure PopupTheDialog Handle hReturnObj Integer iCaller
Send Popup hReturnObj

WebSet psValue of oProcess to (GetCurrentProcessId())
WebSet psValue of oCaller to iCaller
WebSet psValue of oGlobal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
End_Procedure

Function DialogResult Returns String
String sResult

WebGet psValue of oProcess to sResult
Function_Return sResult
End_Function

End_Object

//==============================================================================
// This is the actual view
//==============================================================================
Object oProcPoolDemo is a cWebView
Set piWidth to 700
Set psCaption to "Process Pooling Effects Demo"
Set pbServerOnShow to True

Property Integer[] paiWebAppProcs

// Display this view at start up:
Delegate Set phoDefaultView to Self

// Work out the web application name from the WebServiceDispatcher.wo
// file in AppHTML, which we treat like a .ini file
Function WebAppName Returns String
Handle hoIni
String sName

Get Create (RefClass(cIniFile)) to hoIni
Set psFileName of hoIni to ;
(psAppHtmlPath(phoWorkspace(ghoApplication)) + ;
"\WebServiceDispatcher.wso")
Get ReadString of hoIni "WebService" "Application" "" to sName
Send Destroy of hoIni
Function_Return sName
End_Function

// Will be set to return value of above function at start-up.
// This is a regular property because the web app name can't
// change while the program is running.
Property String psWebAppName (WebAppName(Self))

// This uses three external functions to find all the processes in the
// current WebApp's process pool - it will get updated on every refresh
// so if you change the number of processes in the pool while the WebApp is
// running you will see it in the view.
//
// It first uses EnumProcesses to find all the running processes on the
// machine.
//
// It then iterates through that list and tries OpenProcess to get a handle
// to it (for some permissions will not allow that, so those are skipped).
//
// Finally it calls ProcessImageFileName to see if that is one of the
// processes running for THIS WebApp. However ProcessImageFileName
// returns a file-path starting with the disk identifer in a slightly odd
// form, i.e. "\DEVICE\HARDDISKVOLUMEn" (n is "1" for my C: drive) and even
// spookier things for mapped drives, so we strip off the "C:\", or whatever,
// from the application file name DataFlex returns and uppercase both, then
// compare THAT to the same length of the right-portion of the image name.
// This may screw up if you have more than one identically pathed web-apps
// on different drives - just so you know. <g>
//
// Note: that although the docs (and the declarations) use DWords,
// on Vincent's advice we are using UIntegers in our code (the same
// thing in reality) because you can use SizeOfType(UInteger) in the
// Watches window when debugging, which you can't for DWord.
Procedure FindWebAppProcs
Integer[] aiWebAppProcs
UInteger[] auiProcs
UInteger uiCb uiNeeded uiSize uiErr
Integer iOK i iLast iPos iSize iPathLen
Handle hProc
UChar[] ucaFile
String sPath sImage

Move (Uppercase(GetApplicationFileName(ghoApplication))) to sPath
// Strip off drive designation:
Move (Pos("\", sPath)) to iPos
Move (Right(sPath, (Length(sPath) - iPos))) to sPath
Move (Length(sPath)) to iPathLen
Move 4096 to iSize

Move (ResizeArray(auiProcs, iSize)) to auiProcs
Move (iSize * SizeOfType(UInteger)) to uiCb
Move 0 to uiNeeded

Move (EnumProcesses(AddressOf(auiProcs), ;
uiCb, ;
AddressOf(uiNeeded))) to iOK

// Just for debugging:
If not iOK ;
Move (GetLastError()) to uiErr

Move (uiNeeded / SizeOfType(UInteger)) to iSize
Move (ResizeArray(auiProcs, iSize)) to auiProcs
Decrement iSize

For i from 0 to iSize
Move (OpenProcess(PROCESS_VM_READ + PROCESS_QUERY_INFORMATION, ;
True, auiProcs[i])) to hProc

If (hProc <> 0) Begin // We DID get a handle to the process
Move (ResizeArray(ucaFile, 0)) to ucaFile
Move (ResizeArray(ucaFile, 2048)) to ucaFile
Move (ProcessImageFileName(hProc, ;
AddressOf(ucaFile), 2048)) to uiSize
Move (ResizeArray(ucaFile, uiSize)) to ucaFile
Move (Uppercase(UCharArrayToString(ucaFile))) to sImage
Move (Right(sImage, iPathLen)) to sImage

If (sImage = sPath) ;
Move auiProcs[i] to aiWebAppProcs[SizeOfArray(aiWebAppProcs)]
End

Loop

Set paiWebAppProcs to aiWebAppProcs
End_Procedure

Procedure OnShow
Send UpdateProcInfo
End_Procedure

// Registry object for getting the WebApp info from the registry:
Object oReg is a cRegistry
Set phRootKey to HKEY_LOCAL_MACHINE
Set pfAccessRights to Key_Read

Function BaseKey Returns String
String[] asParts

Move "SOFTWARE" to asParts[0]
Move "Data Access Worldwide" to asParts[1]
Move "DataFlex" to asParts[2]
Move C_DFVersion to asParts[3]
Move "WebApp Server" to asParts[4]
Move "Web Applications" to asParts[5]

// If it is a 64-bit machine:
If (KeyExists(Self, "SOFTWARE\Wow6432Node")) ;
Move (InsertInArray(asParts, 1, "Wow6432Node")) to asParts

Function_Return (StrJoinFromArray(asParts, "\"))
End_Function

Function DWKeyValue String sApp String sVal Returns Integer
Boolean bOK
Integer iVal
String sKey

Move (BaseKey(Self) + "\" + sApp) to sKey
Get KeyExists sKey to bOK

If not bOK ;
Function_Return 0

Get OpenKey sKey to bOK

If not bOK ;
Function_Return 0

Move (ReadDWord(Self, sVal)) to iVal
Send CloseKey

Function_Return iVal
End_Function

End_Object

// Refresh all the displayed information
Procedure UpdateProcInfo
String sApp
Integer iMin iMax

Get psWebAppName to sApp
WebSet psValue of oMinProc to (DWKeyValue(oReg(Self), sApp, "MinPool"))
WebSet psValue of oMaxProc to (DWKeyValue(oReg(Self), sApp, "MaxPool"))
WebSet psValue of oCurrProcs to "Unknown"

WebSet psValue of oCurrProcess to (GetCurrentProcessId())
WebSet psValue of oGlobalVal to giRandom
WebSet psValue of oRegProp to (piRandom(Self))
WebSet psValue of oDBRec to FlexErrs.Recnum

Send FindWebAppProcs
Send GridRefresh of oProcList
Send Focus of oCallServer
End_Procedure

Object oWebMainPanel is a cWebPanel
Set piColumnCount to 8

Object oExplanation is a cWebLabel
Set piColumnSpan to 0
Set psCaption to ;
('This view demonstrates the fact that in a Process' + ;
' Pooled WebApp (which all modern WebApps generally' + ;
' are) you CANNOT rely on the values in global variables,' + ;
' regular properties and database buffers. They change' + ;
' from one server round-trip to the next. ONLY web' + ;
' properties and Data Dictionary values can be relied on.' + ;
' If you run this under the debugger you will see that' + ;
' only a single process is "in the pool" and the values' + ;
' of the things below do not change, which is why you' + ;
' MUST test Web Apps OUTSIDE the debugger.')
End_Object

Object oProcPoolGrp is a cWebGroup
Set piColumnCount to 8
Set piColumnSpan to 0
Set psCaption to "Process Pool Information:"

Object oPoolInfo is a cWebGroup
Set pbShowBorder to False
Set pbShowCaption to False
Set piColumnCount to 12
Set piColumnSpan to 6

Object oAppName is a cWebForm
Set piColumnSpan to 0
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Web Application:"
Set psValue to (psWebAppName(Self))
End_Object

Object oMinProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Minimum Pool:"
End_Object

Object oMaxProc is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Maximum Pool:"
End_Object

Object oCurrProcs is a cWebForm
Set piColumnSpan to 5
Set pbReadOnly to True
Set peLabelAlign to alignRight
Set psLabel to "Current Pool:"
End_Object

End_Object

Object oProcList is a cWebList
Set piColumnIndex to 6
Set piColumnSpan to 2
Set pbDataAware to False
Set pbOfflineEditing to True // DON'T call the server on RowChange
// Adjust this to see more/less process numbers without scrolling:
Set piHeight to 200

Object oProcsCol is a cWebColumn
Set psCaption to "Pool Process IDs"
Set piWidth to 100
End_Object

Procedure OnManualLoadData tWebRow[] ByRef aTheRows String ByRef sCurrentRowID
Integer[] aiWebProcs
Integer i iLast iThis

Get paiWebAppProcs of oProcPoolDemo to aiWebProcs
Move (GetCurrentProcessId()) to iThis

Move (SizeOfArray(aiWebProcs)) to iLast
WebSet psValue of oCurrProcs to iLast
Decrement iLast

For i from 0 to iLast
Move aiWebProcs[i] to aTheRows[i].sRowID
Move aiWebProcs[i] to aTheRows[i].aCells[0].sValue

If (aiWebProcs[i] = iThis) Begin
Move aiWebProcs[i] to sCurrentRowID
End

Loop

Forward Send OnManualLoadData (&aTheRows) (&sCurrentRowID)
End_Procedure

End_Object

End_Object

Object oCurrProcess is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Last invoked server process was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oGlobalVal is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Global variable giRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oRegProp is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Regular property piRandom in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oDBRec is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set pbReadOnly to True
Set psLabel to "Flexerrs recnum in that was:"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oWebValue is a cWebForm
Set piColumnIndex to 0
Set piColumnSpan to 4
Set psLabel to "Your entered value:"
Set psValue to "Hello!"
Set peLabelAlign to alignRight
Set piLabelOffset to 250
End_Object

Object oNote is a cWebLabel
Set psCaption to "(This is a web property - psValue of oWebValue - so will not change unless YOU change it)"
Set piColumnIndex to 4
Set piColumnSpan to 4
End_Object

Object oButtonSpacer is a cWebSpacer
Set piHeight to 20
End_Object

Object oCallServer is a cWebButton
Set piColumnIndex to 0
Set piColumnSpan to 2
Set psCaption to "Call Server"

Procedure OnClick
Send UpdateProcInfo
End_Procedure

End_Object

Object oInfo is a cWebButton
Set piColumnIndex to 2
Set piColumnSpan to 2
Set psCaption to "Info Box"

Procedure OnClick
Integer iProc

Move (GetCurrentProcessId()) to iProc
Send ShowInfoBox ("InfoBox in process" * String(iProc))
Send UpdateProcInfo
End_Procedure

End_Object

Object oYesNo is a cWebButton
Set piColumnIndex to 4
Set piColumnSpan to 2
Set psCaption to "Yes/No"

// Web Property to hold state between browser/server round-trips
{ WebProperty=Client }
Property stAllMyState ptState

// Is called in response to user's second answer:
Procedure ProcessSecondAnswer Integer eAnswer
stAllMyState tState
String[] asInfo

WebGet ptState to tState
Move (GetCurrentProcessId()) to tState.iProc3
Move (CurrentDateTime()) to tState.tmAnswered2
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.SecondAnswer

// Assemble results:
Move ("You clicked the 'Yes/No' button at" * String(tState.tmClicked) * ;
"in process" * String(tState.iProc1)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your first answer was: '" + ;
tState.sFirstAswer + "' at" * String(tState.tmAnswered1) * ;
"in process" * String(tState.iProc2)) ;
to asInfo[SizeOfArray(asInfo)]
Move ("Your second answer was: '" + ;
tState.SecondAnswer + "' at" * String(tState.tmAnswered2) * ;
"in process" * String(tState.iProc3)) ;
to asInfo[SizeOfArray(asInfo)]

Send ShowInfoBox (StrJoinFromArray(asInfo, C_CRLF)) "Results"

Send UpdateProcInfo
End_Procedure
WebPublishProcedure ProcessSecondAnswer // Publish the proc to receive control after second answer

// Is called in response to user's first answer:
Procedure ProcessFirstAnswer Integer eAnswer
stAllMyState tState

WebGet ptState to tState

Move (GetCurrentProcessId()) to tState.iProc2
Move (CurrentDateTime()) to tState.tmAnswered1
Move (If((eAnswer = cmYes), "Yes", "No")) to tState.sFirstAswer
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessSecondAnswer)) ;
("Do you REALLY want to do this? (Proc:" * String(tState.iProc2) + ")") ;
"Second question"
End_Procedure
WebPublishProcedure ProcessFirstAnswer // Publish the proc to receive control after first answer

// Triggers the question cascade:
Procedure OnClick
stAllMyState tState

Move (CurrentDateTime()) to tState.tmClicked
Move (GetCurrentProcessId()) to tState.iProc1
WebSet ptState to tState

Send ShowYesNo Self (RefProc(ProcessFirstAnswer)) ;
("Do you want to do this? (Proc:" * String(tState.iProc1) + ")") ;
"First question"
End_Procedure

End_Object

Object oDialog is a cWebButton
Set piColumnIndex to 6
Set piColumnSpan to 2
Set psCaption to "Popup Dialog"

Procedure OnCloseModalDialog Handle hoModalDialog
Integer iProc1 iProc2

If (hoModalDialog = oTestDialog) Begin
Get DialogResult of oTestDialog to iProc1
Move (GetCurrentProcessId()) to iProc2
Send ShowInfoBox ;
("Dialog in process" * String(iProc1) + C_CRLF + ;
"Returned to process" * String(iProc2)) "Result"

Send UpdateProcInfo
End

End_Procedure

Procedure OnClick
Send PopupTheDialog of oTestDialog Self (GetCurrentProcessId())
End_Procedure

End_Object

End_Object

End_Object
</source>

[[Category: Web Applications]]