DATAFLEX DOS 386 PROTECTED MODE INSTALLATION AND ENVIRONMENT GUIDE

Revision 3*

Copyright 1995 Data Access Corporation

DATA ACCESS CORPORATION Miami, Florida USA Technical Support: (voice) 305.232.3142 (FAX) 305.238.0017 CompuServe Forum: GO DACCESS

October 14, 1995 Part No. 008200-EG * This manual applies to revisions of DataFlex starting with Revision 3.1.

COPYRIGHT NOTICE Copyright 1995 DATA ACCESS CORPORATION. All rights reserved. No part of this publication may be copied or distributed, transmitted, transcribed, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, manual, or otherwise, or disclosed to third parties without the express written permission of Data Access Corporation, Miami, Florida, USA. DISCLAIMER Data Access Corporation makes no representation or warranties, express or implied, with respect to this publication, or any Data Access Corporation product, including but not limited to warranties of merchantability or fitness for any particular purpose. Data Access Corporation reserves to itself the right to make changes, enhancements, revisions and alterations of any kind to this publication or the product(s) it covers without obligation to notify any person, institution or organization of such changes, enhancements, revisions and alterations. TRADEMARKS DataFlex is a registered trademark and Flex-Keys is a trademark of Data Access Corporation. All other brand and product names are trademarks or registered trademarks of their respective companies.

CONTENTS
1 INSTALLING DATAFLEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Whats on the Installation Media . . . . . . . . . . . . . . . . 1.2 Important Notes for Current DataFlex Users . . . . . . . 1.3 System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 Installing the DataFlex 3.1 . . . . . . . . . . . . . . . . . . . . . 1.4.1 Before You Begin . . . . . . . . . . . . . . . . . . . . . . . 1.4.2 DataFlex Product Installation . . . . . . . . . . . . . . 1.5 Registering DataFlex . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 The Sample Applications (Full- Development License Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7 The Read Me Documents . . . . . . . . . . . . . . . . . . . . . . 1.8 Starting DataFlex . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9 Using the DataFlex 3.1 Electronic Guides . . . . . . . . . . 1.10 Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 3 5 5 5 6 10 10 10 10 11 13 15 15 15 17

2 CONFIGURING DATAFLEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Using DFCONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Key Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 User-Counting Concepts . . . . . . . . . . . . . . . . . . . . . . . 2.4 Use of the SHARE command for Windows, Single-User DOS Users, Peer-to-peer networks, and other Networks which require SHARE. . . . . . . . . . . . . . . . . . . . . . . . .

19

Contents

ii

DataFlex for DOS 386 Protected Mode

1 INSTALLING DATAFLEX
The information in this document will assist you in the installation and use of DataFlex 3.1 and its electronic documentation.

1.1 Whats on the Installation Media

The DataFlex 3.1 386 Protected Mode product and documentation are supplied on one CD-ROM disc: Part Number 008200.CD Description CD-ROM disc

The top three levels of the CD-ROM directory structure are arranged as follows: ACROBAT DOS WIN PRODUCTS DF31 DOS OS2 DF31LRT DOS OS2 WINQL4EV STD_EVAL SQL_EVAL DACDOC DF31 WINQL4EV Following are explanations for each of the directories shown above:
1 Installing DataFlex 1

Directory ACROBAT ACROBAT\DOS ACROBAT\WIN

Explanation Divided into two subdirectories. Contains the DOS version of the Acrobat Reader. Contains the Windows version of the Acrobat Reader.

PRODUCTS PRODUCTS\DF31 PRODUCTS\DF31\DOS

Divided into three subdirectories. Divided into two subdirectories. Contains all the necessary files to install a DataFlex 3.1 for DOS 386 Protected Mode Full Development License or a Runtime License. Contains all the files which are necessary to install a DataFlex 3.1 for OS/2 Full Development License or a Runtime License. Divided into two subdirectories. Contains the DOS version of the DataFlex limited runtime. Contains the OS/2 version of the DataFlex limited runtime.

PRODUCTS\DF31\OS2

PRODUCTS\DF31LRT PRODUCTS\DF31LRT\DOS PRODUCTS\DF31LRT\OS2

PRODUCTS\WINQL4EV

Divided into two subdirectories.

DataFlex for DOS 386 Protected Mode

Directory PRODUCTS\WINQL4EV\ STD_EVAL PRODUCTS\WINQL4EV\ SQL_EVAL

Explanation Contains the evaluation version of WinQL Rev. 4.0 standard edition Contains the evaluation version of WinQL Rev. 4.0 SQL edition

DACDOC DACDOC\DF31

Divided into two subdirectories Contains, in Acrobat format, the complete documentation set for DataFlex. Note that the PDF files are not compressed. Contains, in Acrobat format, the complete documentation for WinQL Rev. 4.0.

DACDOC\WINQL4EV

The CD-ROM disc contains the install program for the Windows and DOS versions of the Adobe Acrobat Reader. For information on how to install the Acrobat Reader, please refer to the Acrobat Reader Installation Notes.

1.2 Important Notes for Current DataFlex Users

Here are some points to note about running existing DataFlex programs with the 3.1 runtime: If you plan to install DataFlex as an upgrade to an existing Full Development license, you MUST install it

1 Installing DataFlex

as a new license in a separate area and become sufficiently familiar with the new features. TO RUN A PROGRAM COMPILED WITH ANY REVISION PRIOR TO 3.1, YOU MUST FIRST RECOMPILE THE PROGRAM WITH THE DATAFLEX 3.1 COMPILER. Where you must retain the Flex-Key mappings of Rev. 2.3 for some applications, use the Configuration Utility (DFCONFIG) to create the desired mapping and use the Save As function to create a configuration file with a different name (DO NOT USE THE DEFAULT FILE NAME). Then, before recompiling the applications, add a read_dfini command to the beginning of each program given the filename you chose in Configuration. .FLX files compiled in Revision 3.1 or later cannot be run by earlier revisions of DataFlex! DataFlex 3.05 source code is fully compatible with Revision 3.1 and should compile and operate without problem. If you use the current File Definition Utility to modify (e.g., to add a field or turn header-integrity checking on), a data file created under an earlier revision of DataFlex, the data file will be saved in the new format. As a result, you will thereafter not be able to access the data file with any runtime earlier than Rev. 3.01 or programs compiled under such revisions. Where you must retain the ability to use the earlier revision, modify such files only with the utilities of the earlier revision. Data files created in the format of the current revision will be accessible by all revisions 3.01b or later.

DataFlex for DOS 386 Protected Mode

1.3 System Requirements

The system requirements for this version of DataFlex are: A 386SX-class PC or better. A hard disk drive, with about 12 megabytes of available disk space. The documentation will consume approximately 13 megabytes of additional disk space. MS-DOS or PC-DOS Version 6.1 or higher. Note: this version of DataFlex is not supported for use under OS/2. To run DataFlex under OS/2, please use the version of DataFlex designated for that environment. EMM386 or QEMM 386 Version 7.0 (included with your DOS). 2.5 megabytes of free EMS or XMS. Note that you cannot add EMS and XMS memory together to yield 2.5 megabytes. Depending on the size of your application, this memory requirement may need to be increased. Share should be loaded. The recommended setting is SHARE /F:8192 /L:500.

1.4 Installing DataFlex 3.1

1.4.1 Before You Begin
The installation process is highly automated, and will offer you a number of choices as it proceeds. It will be helpful if you first:

1 Installing DataFlex

 Check the System Requirements above and verify that you have everything required to run DataFlex. Decide whether you wish to install the Sample Applications (highly recommended for both first-time users and seasoned developers).

1.4.2 DataFlex Product Installation

The following steps will install DataFlex on your system. 1. Start up your computer or network server (log in as the system administrator or most-privileged user) as you normally do. Place the CD-ROM disc labeled "Object-Oriented 4GL Application Development Environment DBMS Revision 3.1" in your CD-ROM drive, and switch to that drive. Change to the \PRODUCTS\DF31\DOS subdirectory. At the DOS command line, type INSTALL e The first screen displayed asks you to verify the drive letters and the directory name. If they are not correct, or if one or more were omitted, then you may change them at this point. The second screen displayed will show the version of DataFlex you are installing. Read this description carefully so as to avoid installing the wrong version of DataFlex. Follow the succeeding screen prompts carefully. If at any time you need to stop installation, press c+C. If the installation program displays one or more operating system error messages, you should take note of them; correct their cause, then rerun the installation program.

2.

3. 4.

5.

6.

DataFlex for DOS 386 Protected Mode

Examples of errors are: disk full; cant create directory; drive not ready; write protected; or invalid drive. 7. The files of DataFlex are copied onto your hard drive in a logically designed directory structure under the main directory you specified at the beginning of the installation (or under the default, \FLEX). You may change the location of the files if you wish, but it is suggested you do not, unless you have particular reasons to do so. The installation process includes the writing of a batch file which you can call to set the environment variables PATH, and DFENV, so that DataFlex can find all the correct files when they are needed. This batch file, named SETPATH.BAT, is located in the USR directory under the main directory where you installed DataFlex. You can either run it manually each time you want to run DataFlex, or you can add its commands to your AUTOEXEC.BAT file so that the environment variables are set automatically each time you boot your computer. The DFENV environment variable allows you to specify the full path of an ASCII file containing environment settings. For example, you may create a file named DFENV.CFG under the \FLEX\USR subdirectory. In this file you may include a string value for the DFPATH environment variable, which contains the name of the directories searched on your disk drive(s) when you are opening, creating, deleting, renaming, or copying DataFlex files. To actually use the string value, you must set the new environment variable, DFENV, to the name of the configuration file (i.e., DFENV.CFG). One of the benefits of using this mechanism is that you can specify an extremely long DFPATH value without worrying about Operating System limitations. Furthermore, you may include any number of DataFlex environment variables in this configuration file.
1 Installing DataFlex 7

By default, DataFlex installs a configuration file, named DFENV.CFG, in your USR directory. It is important to note that the string value defined in this file will supersede your current DFPATH setting. 8. The installation program creates a directory structure beneath the destination path that you specified during the installation procedure. Below is a visual representation of the directory structure for a Full Development License, assuming your destination path is FLEX:

BIN

Contains all executable files and all utilities written in DataFlex. Contains any non-executable product not normally changed by the user:
DataFlex for DOS 386 Protected Mode

LIB

ALLENTRY.FLP ALLENTRY.PKI FLEX.CFL *.FLX SRC

+ +

Divided into two subdirectories. Contains all the DataFlex UIMS package files.
+

SRC\PKG

SRC\SOURCE

Contains all the DataFlex source files (*.SRC) and all the packages for the DataFlex 3.1 utilities. Contains all the DataFlex configuration files as well as several sets of database related files.
+

USR

USR\EXAMPLES

Contains seven subdirectories with various sample applications and example programs. USR\HELP
+

Contains the DataFlex context-sensitive help data files.

Directories so marked are supplied only with development licenses

9.

After all of the files are placed onto the hard disk, a message will appear, informing you of the fact that the installation process has been completed. The installation program will ask you whether you want to start the setup program DFSETUP. This program is used to install your registration code. The registration instructions below will take you through this process step by step.

1 Installing DataFlex

Note:

Runtime installation may require extra installation steps, as provided by the application vendor.

1.5 Registering DataFlex

The setup utility DFSETUP will start at the end of the installation process if you confirm that you wish it to. This utility is discussed in more detail in the "Setup and Configuration" chapter of the DataFlex Users Guide. Its purpose is to register your license and create the user-counting file.

1.6 The Sample Applications (FullDevelopment License Only)

Once you have successfully installed DataFlex, we strongly suggest that you run and examine the Sample Applications supplied with DataFlex in Directory \FLEX\USR\EXAMPLES. This is the best way to become familiar with DataFlex.

1.7 The Release Notes

Be sure to read the Release Notes. It contains up-to-the-minute information on program, feature, and command changes and additions.

1.8 Starting DataFlex

To execute DataFlex, follow these steps:

10

DataFlex for DOS 386 Protected Mode

1.

If you have modified the CONFIG.SYS or AUTOEXEC.BAT files, shut down and reboot your computer so that the new settings will take effect. If you have not modified AUTOEXEC.BAT, you must run SETPATH to set up PATH and DFENV. To do this, from the \FLEX directory, type .\USR\SETPATH at the command line. You may now start DataFlex by typing FLEX or DFRUN and pressing e. At this point, the DataFlex Menu should appear. You may now test to see that DataFlex is working properly. Once in the DataFlex menu system, press a+4 to return to the operating system.

2.

3.

4.

1.9 Using the Electronic Documentation

As previously mentioned, the PDF files contained in the \DACDOC\DF31 directory on the CD-ROM disc constitute the electronic version of the entire 3.1 documentation. In order to view the information in these files, you must open the files with the Acrobat Reader. Therefore, if you have not yet installed the Acrobat Reader, you should do so now (see the Adobe Acrobat Reader Installation Notes). Opening PDF files with the Acrobat Reader is as simple as opening a document in your favorite word-processing software. In fact, every time you run the Acrobat Reader software, a dialog appears prompting you for the name of the PDF file to open. You may choose to open the file here, or select File from the Main Menu; both methods are valid. The documentation files are:

1 Installing DataFlex

11

UPDT305.PDF

Update guide to DataFlex 3.05 from DataFlex 3.01. The update guide to this revision. The Developing Applications with DataFlex manual. The DataFlex Users Guide. The DataFlex UIMS Reference.

UPDT31.PDF DFAPPDEV.PDF

USRGUIDE.PDF UIMSREF.PDF

HANDBOOK.PDF The DataFlex UIMS Handbook. ENCY.PDF READ31.PDF The DataFlex Encyclopedia. The DataFlex 3.1 Release Notes

HOMECARD.PDF This file is the starting point or "home page" for all the files listed above. As such, it contains hot links, which can be clicked on, to each of the files. Note that the links in this file do not work with the Adobe Acrobat Reader 1.0 for DOS. Aside from the files shown above, there is one more file in the \DACDOC\DF31 directory. This file, named DF31.PDX, contains the cross-index for all of the PDF files listed above. To access this file, you must have the Acrobat Search Plug-In product, which can only be obtained by purchasing the Adobe Acrobat Exchange package. The Adobe Acrobat Exchange package not only provides you with the interface to a full-text index-based search system, but also enables you to create, annotate and modify PDF files. If you decide to distribute your own PDF files, you can also purchase the Acrobat Catalog product to create full-text
12 DataFlex for DOS 386 Protected Mode

indexes for collections of PDF files, such as the cross-index for the DataFlex documentation. For more information about Adobe Acrobat, you may contact Adobe Systems at (800) 27-ADOBE.

1.10 Technical Support

We provide technical support via phone, FAX, and CompuServe Forum, DACCESS. Our FAX number is 1.305.238.0017. On CompuServe, our Forum may be accessed with the GO DACCESS command. In either medium, please enable us to reply by providing your name as well as return ID or telephone number. Also identify the DataFlex components in use, and the hardware and software environment you are using it in.

1 Installing DataFlex

13

14

DataFlex for DOS 386 Protected Mode

2 CONFIGURING DATAFLEX
2.1 Using DFCONFIG
The Configuration Utility (DFCONFIG) allows you to optionally set certain attributes such as screen colors and what function keys to use, which characters to use to represent money amounts, and how to format dates. Note: In previous revisions of DataFlex 3, the Setup Utility allowed you to modify the DataFlex screen colors. In 3.1, you must use the DFCONFIG utility instead.

2.2 Key Assignments

Your DataFlex package comes with certain function keys already assigned, so that they comply with IBMs SAA/CUA specifications. If you wish to change any of these assignments, then you must run the DataFlex Configuration Utility (DFCONFIG). Refer to the DataFlex Users Guide for more information about DFCONFIG. See the paragraph under "The Installation Program" above about Flex-Key functionality of programs compiled under earlier revisions of DataFlex and running under the current revision. The default function key assignments are shown in the following tables, with those defined in Data Access packages followed by an asterisk (*):

2 Configuring DataFlex

15

KEY

s + KEY

c + KEY

a + KEY
User Key 1

1 2 3 4

Help Save Record Exit Function Prompt Print Screen Delete Record Trace Mode*

User Key 2

Exit Application Clear All Panels Switch to Prev Panel* Calculate Switch to Next Panel*

5 6

Clear Area Switch to Next Area

Refresh Screen Switch to Prev Area

7 8 9 0 e t i

Find Previous Find Next Find Switch to Action Bar Accept Next Item Insert/Overtype Toggle Delete Character Cursor Left Cursor Right Cursor Up Cursor Down Selection Toggle Destructive Backspace Begin of Line

Superfind Previous Superfind Next Superfind Add Mode On/Off* Clear and Return Previous Item Trace On/Off* Zoom

d l r u v g b

Skip Word Left Skip Word Right Begin of Panel End of Panel

Erase to End of Line Begin of Data

Non-WP backspace

16

DataFlex for DOS 386 Protected Mode

KEY

s + KEY

c + KEY
End of Data Scroll Page Left Scroll Page Right

a + KEY

z o p

End of Line Scroll Page Up Scroll Page Down

q \ _ + _

Escape (Cancel) Mark Paste Copy Cut

2.3 User-Counting Concepts

Upon execution of the DFSETUP program, a file will be created to count users on a LAN. This file, which is usually stored in the directory where DFSETUP was executed, will have a root name equivalent to your serial number and an extension of .DFR. For example, if your serial number is 440,000, then the .DFR file will be named 440000.DFR. Only one copy of the .DFR file should exist for any one serial number and that file must be accessible, via DFPATH, to all users who use that serial number. If the DataFlex executables are installed on multiple servers to improve network performance, the .DFR file cannot be copied. To move a copy of the .DFR file, you must first move the DFSETUP program to the target directory. Then, run the DFSETUP program and select Option 3, "End Registration Save Changes. This will have the effect of re-creating the

2 Configuring DataFlex

17

.DFR file in the new directory. Any old .DFR files must then be deleted. A .DFR file should NOT be moved, except by DFSETUP. Attempting to move the file or having more than one .DFR file for the same serial number may cause the file to be rejected. Following this discipline will also ensure that your .DFR file will be compatible with future revisions of DataFlex. If the .DFR file is damaged in any way, you will receive an appropriate error message when you try to run DataFlex. You may re-create the .DFR file by running the DFSETUP program and selecting Option 3. When the maximum number of users are using DataFlex and another user attempts to start it, that user will receive a message explaining the condition and will not be able to start DataFlex. The user will be able to start DataFlex as soon as one or more of the current users exits DataFlex. To correct this situation over the long term, you may purchase an increase in the maximum number of concurrent DataFlex users from your dealer.

2.4 Use of the SHARE command for Windows, Single-User DOS Users, Peerto-peer networks, and other Networks which require SHARE.
A multi-user operating system (like NetWare) has built-in functionality to handle multi-user access to files on the network. PEER to PEER network operating systems (like LanTastic) and single-user operating systems (DOS) require that the DOS SHARE command be issued to add file sharing

18

DataFlex for DOS 386 Protected Mode

and locking functionality to the operating system kernel. Also, even though Windows 3.1 is a multitasking operating system, it does not have inherent support for file sharing and requires that the DOS SHARE command be loaded prior to running Windows. Note that Windows for Workgroups version 3.11 does have built-in support for file sharing; therefore, you do not have to load the DOS SHARE command before running Windows. When do you need to load SHARE? You only need to load SHARE if you are NOT using an operating system which already has SHAREs functionality built in (like Novells NetWare) and you are accessing files in a multi-user fashion. Accessing files in a multi-user fashion could mean actually having multiple users open and use the file (like on LanTastic), having multiple tasks accessing the same files (like under Windows or DesqView), or running DataFlex programs (whether single- or multi-user) that open the same file more than once concurrently. How can you determine whether such a condition applies to your system? Check for any of the following conditions: 1. If you use the chain wait command to invoke a second DataFlex program, and that program opens one of the same files in use by the original program, SHARE is needed. Note, if you use the export_files option, then SHARE is not needed, since both programs will share the same file buffer and handles. If you use file aliasing methods, you need SHARE loaded. This is the process of defining multiple files in FILELIST.CFG with different DataFlex names but using the same physical rootname. If you are using the File Definition Utility and you open a file, and then execute a maintenance option. This invokes
19

2.

3.

2 Configuring DataFlex

the File Maintenance Utility, a separate program, which could access the same files that File Definition already has opened. SHARE is needed in this case. This is of concern only for users of development licenses, since File Definition is not part of a runtime license. 4. THE FOLLOWING TEST SHOULD NOT BE PERFORMED ON LIVE DATA! This test consists of two machines, named A and B, which are running DataFlex and accessing the same data file(s). Machine A finds a record and performs a lock on that record. Machine B Finds, Edits, and attempts to Saves the same record. If Machine B can successfully save the record, then Share is required. The expected behavior is for Machine B to wait indefinitely for machine A to release the lock.

If you are using an operating system which does not have SHARE support built in and you are doing one of the above three items, you need to load SHARE. Also, if SHARE is active on any computer that is using DataFlex, you must increase the command line parameters to the proper amount, as shown below. How do you load SHARE? Simply add the line SHARE to your AUTOEXEC.BAT file. This loads SHARE with the default parameters. There are two parameters used when loading SHARE: the L and F parameters. They define the size of two separate tables that SHARE maintains. The first, L, is the size of the SHARE LOCK table. The L parameter defines the number of locks that SHARE can keep track of. The default L parameter is 60. Set the L parameter to a number equal to the number of locks you expect to want plus a bit of extra space. Note that DataFlex will issue a maximum of one lock per data file.

20

DataFlex for DOS 386 Protected Mode

The F parameter specifies how many bytes are allocated to the file handle table. This table stores the complete pathname of the file plus 11 bytes of overhead per file. Thus C:\DATAFLEX\DATA\DOUG.DAT would require 36 bytes in the file handle table. The default for the F parameter is 2048, which will allow you to open around 20 files with large file paths. Increase this number as needed for your application. Keep in mind that SHARE is not a per-process setting, but a per-machine setting. Thus, if you want to run 5 different programs at the same time on the same machine, each one opening 30 files, the F parameter in SHARE would need to be large enough for 150 files. Also, the L parameter would need to be able to handle the 150 potential locks. Here is an example of loading SHARE, increasing the F parameter to 8192 and the L parameter to 500: SHARE /F:8192 /L:500 If SHARE is not loaded and you attempt multi-user access (and you are not using an operating system with SHARE capabilities built in) file corruption can occur. If you install SHARE with insufficient settings for the F or L parameters, a variety of DataFlex errors may result such as: Cant open datafile, Too many locks, Read error on index file, Seek to unwritten extent, etc. The corruption can occur due to DOS keeping a separate buffer and file handle for the same file in two different applications. When records are added or edited in one file, the other (really the same physical file) does not get updated. With SHARE, all files opened with the same physical name share the same buffers, regardless of which application opened them. Note that the above setting would use 11692 bytes: 8192 for the F parameter and 3500 for the L parameter (each lock requires 7

2 Configuring DataFlex

21

bytes of overhead). For more information on SHARE, consult your DOS documentation or contact your DOS manufacturer.

22

DataFlex for DOS 386 Protected Mode