Paradox Table Formats and Network Locking Protocol

Since there seems to be confusion concerning the different versions of the 
Paradox table formats and locking protocols, we have prepared this document.  
This document will try to explain the differences and similarities of these 
locking protocols by providing an overview.  This document will discuss the 
four different variations of the Paradox locking protocol: Paradox 3.5, 
Paradox Engine 2.0, and earlier; Paradox 4.0;  Paradox Engine 3.0; and the 
DataBase Desktop.  For specific implementations please see the respective user 
guides, programming guides, and programming references for Paradox, Paradox 
Engine, or other Paradox aware applications that you are running.


Table and field types and features supported

There are actually a number of Paradox table types.  Starting with version 2.0 
of Paradox, each major new release of Paradox has changed and improved the 
table structure.  All Paradox table types from Paradox 1.0 through Paradox 3.5 
are compatible with each of those versions of Paradox.  So a table created in 
Paradox 1.0 is compatible with Paradox 3.5 and vice versa.  A table created in 
Engine 2.0 can be read by Engine 1.0.  So Paradox 3.5 /Engine 2.0 or earlier 
can read, write and create tables that are compatible with Paradox 1.0 through 
Paradox 3.5 /Engine 1.0 through Engine 2.0.  

Paradox 4.0 adds a new data type to the table format: Binary Large Objects, 
commonly known as BLObs and new types of Secondary Indices.  Paradox 4.0 
supports two types of BLOb fields: Memo, and BLOb.  Versions of Paradox prior 
to 4.0, or the Engine prior to 3.0, cannot read, write, or create this new 
table format.  If  you attempt to read or write a Paradox 4.0 table type in an 
earlier version of Paradox, it will return an error that the table is password 
protected.

Paradox 4.0 can read, write, and create Paradox table types that are 
compatible with Paradox 1.0 through Paradox 4.0.  So a table created in 
Paradox 1.0 is compatible with Paradox 4.0.  A table created in Engine 1.0 or 
2.0 can be read by or written to by Paradox 4.0.  

Paradox and the Engine do not change the table type when reading or writing.  
The table type is only changed when a Modify | Restructure is performed on the 
table in Paradox or the PxTableUpdate() Engine 3.0 function is called.


Table Formats Supported

The following table lists which Borland products support which Paradox table 
format.

Paradox 1.0 through 3.5             Paradox 4.0

Paradox 1.0 - 4.0                   Paradox 4.0
Paradox Runtime 2.0 - 4.0           Quattro Pro 4.0
Quattro Pro 2.0 - 4.0               Quattro Pro for Windows
Quattro Pro for Windows             DataBase Desktop
DataBase Desktop                    ObjectVision 2.1
ObjectVision 1.0 - 2.1              Paradox Engine 3.0
SideKick 2.0                        ODAPI Engine
Reflex 2.0                          Paradox for Windows
Paradox Engine 1.0 - 3.0
ODAPI Engine


Paradox Locking Protocols

There are two different Paradox locking protocols: the protocol introduced 
with Paradox 2.0 and the protocol introduced with Paradox 4.0.  These two 
protocols are not compatible with each other.  The locking protocol has no 
bearing on which type of table a program can work with.  There are a few 
programs that can support either locking protocol, however these programs can 
only support one protocol at a time.


Paradox 2.0 Locking Protocol 

The Paradox 2.0 locking protocol is the only protocol available for Paradox 
and Paradox Runtime versions 2.0 through 3.5 and Paradox Engine versions 1.0 
through 2.0.  It is also the locking protocol used by Borland applications 
built with versions 1.0 or 2.0 of the Paradox Engine, such as: Quattro Pro 2.0 
- 4.0, Object Vision 1.0 - 2.0, and SideKick 2.0.  The designation "Paradox 
2.0 locking protocol" represents this level of concurrency.


Network Control File

The Paradox network control file, PARADOX.NET serves as the reference point 
for all lock files created by Paradox and the Engine. Each lock file 
references the network control file, so each user must map to the same network 
control file in the same way.  For example, if you are using volume DATA on 
file server SERVER_1 and the network control file is in the directory 
\PDOXDATA each user must map \\SERVER_1\DATA:\PDOXDATA the same way, using the 
same drive letter.  If the network you are using does not have volumes, then 
DATA would be a directory off the root of SERVER_1.  If you are mapping 
\\SERVER_1\DATA to the root of drive P: then each Paradox system would specify 
the location of PARADOX.NET as P:\PDOXDATA\.


Directory Locks

Paradox places a locking file, PARADOX.LCK, in each directory where tables are 
being accessed.  This locking file regulates concurrent access to files in the 
directory.  The lock file references PARADOX.NET, so every user must map to 
the data directory the same way using the same drive letter and path.  


Shareable Directories

When Paradox, or Paradox Engine applications need to access tables in a 
directory, they place a "Shareable" PARADOX.LCK file in that directory.  This 
designation simply means that other Paradox/Engine users can access tables in 
that directory.  In Paradox this is known as a "Working" directory.


Exclusive Directories

Paradox and Paradox Runtime also need a directory to store temporary files, 
such as the Answer table from a query.  When Paradox or Paradox Runtime start, 
they also place an "Exclusive" PARADOX.LCK file in a directory, designating 
that directory for temporary files.  This designation means that other 
Paradox/Engine users cannot access tables in that directory.  The Paradox 
Engine does not provide a method of creating an exclusive PARADOX.LCK file.  
In Paradox this is known as a "Private" directory.  (These "Exclusive" 
directory locks are also important with Paradox 4.0.)


Table Locks

The Paradox 2.0 locking protocol places a separate lock file, TablName.LCK, 
for each table being accessed.  That table does not necessarily have to exist 
when the lock file is created.  The table lock file holds all of the locking 
information for that table.  For example, if three users are viewing 
CUSTOMER.DB, the CUSTOMER.LCK file will have a shareable lock listed for each 
of those three users.


Possible Conflicts and Limits

There is one major limit of the Paradox 2.0 locking protocol, the "Form Lock."   
Paradox 3.0 introduced the multi-table form and along with it a need to 
enforce referential integrity between the tables.  The solution was to limit 
concurrent co-editing access to users working with the same form, hence the 
name "Form  Lock."   This would appear as a Write Lock to other Paradox users 
working with the same tables, but not in the same form.  

The Form Lock activates when a user accesses tables via a multi-table form in 
co-edit mode.  From that point all other users who want to co-edit those 
tables must use the same multi-table form.  This restriction remains in effect 
until all users working with those tables are out of co-edit mode.


Paradox 4.0 Locking Protocol

The Paradox 4.0 locking protocol is the only protocol available for Paradox 
4.0 and the ODAPI Engine. Applications written with the Paradox Engine library 
version 3.0 are capable of switching which locking protocol they use.  The 
designation "Paradox 4.0 locking protocol" represents this style of locking 
and concurrency.


Network Control File

The Paradox network control file, PDOXUSRS.NET, serves as the reference point 
for all lock files created by Paradox. Each lock file references the network 
control file, so each user must map to the same network control file in the 
same way, but not necessarily with the same drive letter.  For example, if you 
are using volume DATA on server SERVER_1 and the network control file is in 
the directory \PDOXDATA each user must map \\SERVER_1\DATA:\PDOXDATA the same 
way, however, each user should, but is not required to use the same drive 
letter.  If the network you are using does not have volumes, then DATA would 
be a directory off the root of SERVER_1.  If you are mapping \\SERVER_1\DATA 
to the root of drive P: then each Paradox system would specify the location of 
PARADOX.NET as P:\PDOXDATA\.  However, other users could map \\SERVER_1\DATA 
to the root of drive O: and specify O:\PDOXDATA\ as the location of the 
network control file.


Directory Locks

Paradox 4.0 places a locking file, PDOXUSRS.LCK, in each directory where 
tables are being accessed.  This locking file regulates concurrent access to 
files in the directory.  This is not to be confused with the "Dir Lock" 
feature in Paradox 4.0 (see Paradox 4.0 User's Guide, pg. 662).  The lock file 
references PDOXUSRS.NET, so every user must map to the data directory the same 
way.  It also places an exclusive PARADOX.LCK file in the directory as well.  
It does this to prevent versions of Paradox or the Engine using the older 
locking system from inadvertently accessing tables.


Shareable Directories

When Paradox or Paradox Runtime needs to access tables in a directory, they 
place a "Shareable" PDOXUSRS.LCK file in that directory and an "Exclusive" 
PARADOX.LCK file in that directory.  This designation means that other Paradox 
4.0 users can access tables in that directory.  The exclusive PARADOX.LCK file 
is placed in this directory to keep the older, incompatible locking protocol 
from putting data at risk.  In Paradox, this is known as a "Working" 
directory.


Exclusive Directories

Paradox and Paradox Runtime also need a directory to store temporary files, 
such as the Answer table from a query.  When Paradox or Paradox Runtime start, 
they also place an "Exclusive" PDOXUSRS.LCK file in a directory and an 
"Exclusive" PARADOX.LCK file in the same directory, designating that directory 
for temporary files.  This designation means that other Paradox users cannot 
access tables in that directory.  In Paradox this is known as a "Private" 
directory.


Table Locks

Paradox 4.0 places each table lock in the directory locking file: 
PDOXUSRS.LCK, it no longer uses the separate table lock file of previous 
versions.  For example, if three users are viewing the CUSTOMER.DB table and 
one user is restructuring the ORDERS.DB table, the PDOXUSRS.LCK file will have 
a sharable lock listed for each of those three users who are viewing the 
CUSTOMER.DB table and an exclusive lock on ORDERS.DB for the user who is 
restructuring that table.


Benefits

The major benefits of the Paradox 4.0 locking protocol are the replacement of 
the "Form Lock"  and the removal of separate table lock files.  The "Form 
Lock" has been replaced by a new lock protocol called a "Group Lock."  See 
Technical Information Bulletins 1063, An Explanation of Paradox 4.0 Locks and 
1109, Record Locks on a Network in Paradox 4.0 for more information about 
"Group Lock."   With the removal of separate table lock files, the Paradox 4.0 
locking protocol also reduces number of files needed to maintain concurrent 
access.  These improvements should increase table concurrency and reduce 
network access time.


Concurrency

Application concurrency can be confusing here because different versions of 
different programs support different locking protocols and therefore different 
levels of concurrency.  This section describes the issues involved in multi-
user environments and how to configure different Paradox aware applications.


Multiple Users

Paradox keeps track of the number of concurrent users of the Paradox system 
using the network control file. The Paradox serial number determines the 
number of  user counts.  With the PARADOX.NET file, from the Paradox 2.0 
locking protocol, there are spaces or slots for a total of 150 serial numbers.  
With the PDOXUSRS.NET file, from the Paradox 4.0 locking protocol, there are 
now spaces or slots available for a maximum of 300 concurrent serial numbers.  
Each serial number can define up to 90 user counts.  Each Paradox user must 
have a serial number to get on to the system, however more than one user can 
use a serial number.  Each serial number only consumes one slot in the network 
control file.

Instead of having serial numbers, Paradox Runtime and Paradox Engine increment 
the number of current users and increment the number of  user counts available 
at the same time.  However, each instance of Paradox Runtime or the Paradox 
Engine will use one serial number slot.  When running under Windows, the 
Paradox Engine increments the user counts only once for all instances of any 
Windows Engine applications running in that Windows session.


Paradox 2.0 Locking Protocol Concurrency

In a multi-user environment, the Paradox 2.0 locking protocol maintains 
concurrency through the PARADOX.NET file.  All users who want to share Paradox 
tables must map to the same PARADOX.NET file in the same way using the same 
drive letter and path.  Paradox places a PARADOX.LCK file in each directory 
where tables are being accessed.  Each user who wants to share tables in that 
directory must map that directory the same way using the same drive letter and 
path.  Paradox then places a TablName.LCK file for each table that is being 
used.  This Table lock file holds all of the different locks currently placed 
on that table.


Paradox 4.0 Locking Protocol Concurrency

In a multi-user environment, the Paradox 4.0 locking protocol maintains 
concurrency through the PDOXUSRS.NET file.  All users who want to share 
Paradox tables must map to the same PDOXUSRS.NET file in the same way using 
the same path, but not necessarily the same drive letter.  Paradox places a 
PDOXUSRS.LCK and an exclusive PARADOX.LCK file in each directory where tables 
are being accessed preventing previous versions of Paradox from accessing 
files in the same directory.  Each user who wants to share tables in that 
directory must map that directory the same way using the same drive letter and 
path.  Paradox then places all of the locking information for that table in 
the PDOXUSRS.LCK file, reducing the number of files needed.


Locking Protocols Supported

The following table lists which Borland products support which Paradox locking 
protocol.

Paradox 2.0                   Paradox 4.0              Either

Paradox 2.0 - 3.5             Paradox 4.0              Quattro Pro 4.0     
Paradox Runtime 2.0 - 3.5     DataBase Desktop         Quattro Pro for Windows
Quattro Pro 2.0 - 3.0         Paradox for Windows      ObjectVision 2.1
ObjectVision 1.0 - 2.0	      ODAPI Engine             Paradox Engine 3.0
SideKick 2.0                  Paradox Runtime 4.0
Paradox Engine 1.0 - 2.0


Configuring Specific Applications

This section explains how to configure different Borland applications that are 
Paradox aware.


Paradox

You configure Paradox for multi-user environments during installation or with 
the NUPDATE.EXE program (short for Network Update).  In screen four (see 
below) you can designate the network type and the location of the network 
control file.  When completed, this information is written into the 
PARADOX.SOM file.

There are also command line options that override the settings in PARADOX.SOM: 
-share and -net.  The -share command line option forces Paradox to treat the 
local hard disk as a network drive.  The MS-DOS SHARE.EXE program must be 
loaded into memory before starting Paradox with this command line option.  The 
-net command line option forces Paradox to use or create a network control 
file in the location specified after -net.  A trailing backslash is required.  
For example: PARADOX -NET C:\DATA\

Paradox 4.0 has a User Interface compatibility mode.  This compatibility mode 
does not change Paradox's locking protocol to be compatible with Paradox 3.5. 
There is no way to force Paradox 4.0 to use the older style locking protocols.  
The compatible User Interface mode also does not force Paradox 4.0 to create 
compatible tables.  However, there are three different ways to tell Paradox 
4.0 to create or restructure tables in compatible format: the Custom 
Configuration Program, the FileFormat menu in Create or Restructure, or the 
command line switch -compfile.


Quattro Pro for DOS

Quattro Pro for DOS uses the Paradox Engine.  Versions 2.0 - 4.0 use versions 
1.0 - 2.0 of the Paradox Engine.  Quattro Pro 4.0, with files dated 9/12/92, 
uses version 3.0 of the Paradox Engine.  Set the location of the Paradox 
network control file by choosing the menu selections:  Options | Other | 
Paradox Access |  Paradox Net file.  Set the network type by choosing Options 
| Other | Paradox Access | Network Type.  With version 4.0, files dated 
9/12/92, you will set the locking protocol with an MS-DOS environment variable 
PXLOCKINGSTYLE.  With the default value of 0, Quattro Pro will use the Paradox 
2.0 locking protocol.  With the value set to 1, Quattro Pro will use the 
Paradox 4.0 locking protocol.  The example below will tell Quattro Pro 4.0, 
files dated 9/12/92, to use the Paradox 4.0 locking protocol.

	SET PXLOCKINGSTYLE=1

Quattro Pro 4.0, files dated 9/12/92, will also determine the file type it 
creates using this environment variable.  With a value of 0, Quattro Pro will 
create a Paradox 3.5 table; with a value of 1, Quattro Pro will create a 
Paradox 4.0 table.


SideKick

SideKick 2.0 uses version 1.0 of the Paradox Engine.  It will appear as a 
Paradox 3.0 application in any netfile listing.  You configure SideKick for 
network access using the SKCONFIG.EXE program.  Its opening screen will have a 
selection for Network, select that to bring up the Network dialog box.  You 
can select the Network Type and the Network control file directory in this 
dialog box.  SideKick will share files on the local hard disk when SHARE.EXE 
is loaded and a network type of Unknown(DOS 3.1) is selected.  After defining 
the SideKick's network configuration, choose Save Configuration from the 
opening menu, then choose Exit.


Paradox Engine Applications

The Paradox Engine defines network parameters with PXNetInit() function.  The 
programmer decides the type of network, the locking protocol used, and the 
location of the network control file with parameters to this function.   For 
more information about this Paradox Engine function see the Paradox Engine 
User's Guide.


Engine 3.0 Locking 

The Paradox Engine 3.0 has two locking modes, standard and compatible.  The 
Paradox Engine 3.0 is capable of operating in either Paradox 2.0 locking or 
Paradox 4.0 locking.  The locking protocol choice is made by a call to the 
appropriate Engine function for non-Windows applications.  For Windows 
applications it is made with a call to PXWinInit() and written into the 
WIN.INI file using PXENGCFG.EXE.  Quattro Pro 4.0p, ObjectVision 2.1, and 
Quattro Pro for Windows all use the Paradox Engine 3.0.  (See below for 
information on the DataBase Desktop.)


Compatible Mode

In compatible mode, Engine 3.0 uses the Paradox 2.0 locking protocol.  In this 
mode it will support the concurrency of Paradox 3.5/Engine 2.0.  However, it 
will still allow access to tables in the Paradox 4.0 format.  


Standard Mode

The Paradox Engine 3.0 when set to Paradox 4.0 or standard locking supports 
concurrency with Paradox 4.0.  When creating a table with the Engine you can 
use the appropriate function to set which table type the engine will create, 
Paradox 3.5, or Paradox 4.0.


Paradox Engine Windows Applications

You define the network configuration of Paradox Engine Windows applications 
with the PXENGCFG.EXE program.  This program writes information into the 
WIN.INI file.  You define the location of the Network control file, the 
locking protocol, and whether to share local tables.  You also define the User 
Name that will appear in the network control file.

The locking protocol selection does not necessarily control the file type 
created.  Check the application's documentation for file type selections.


ODAPI Applications

DataBase Desktop and Paradox for Windows Locking and Tables (ODAPI)The Quattro 
Pro for Windows DataBase Desktop and Paradox for Windows use a new component 
of the Borland Object Component Architecture, the Object DataBase Application 
Programming Interface, also known as ODAPI, or the Borland Interbase Local 
Engine.  This protocol behaves the similarly to the Paradox Engine 3.0 running 
in Standard locking mode.  However, the DataBase Desktop also requires the 
designation of "Working" and "Private" directories like Paradox 4.0.


Configuring ODAPI

You can configure ODAPI using the ODAPI configuration program, ODAPICFG.EXE.  
You can set the location of the network control file and whether ODAPI will 
share local tables with other programs using the Paradox 4.0 locking protocol.  
When specifying the location of the network control file, a root directory 
cannot be used.  You must specify some other directory in the format: 
C:\DATA\, with the trailing backslash.


Local Settings

The WIN.INI file holds the locations of the ODAPI.CFG file, the DataBase 
Desktop "Working" directory, and the DataBase Desktop "Private" directory.  
You can use any text editor to change these designations in the WIN.INI file.  
The location of the ODAPI.CFG file is CONFIGFILE=<full drive, path, and file 
name> or CONFIGFILE01=<full drive, path, and file NAME> in the [ODAPI] group.  
The locations of the DataBase Desktop "Working" and "Private" directories are 
in the [DBD] group as WORKDIR=<full drive and directory>, and PRIVDIR=<full 
drive and directory>.  The locations of the Paradox for Windows "Working" and 
"Private" directories are in the [PDOXWIN] group as WORKDIR=<full drive and 
directory>, and PRIVDIR=<full drive and directory>.


Program Startup

This section describes the specific startup or initialization sequences for 
each type of program: Paradox, Paradox Runtime, and Paradox Engine 
applications.


Paradox Startup

When Paradox starts, it attempts to access the network control file specified 
in the PARADOX.SOM file.  If there is a PARADOX.NET file available, Paradox 
will open the file.  If a PARADOX.NET file is not found, Paradox will create a 
new PARADOX.NET file, place a serial number in it and continue with the 
startup process.  After opening the PARADOX.NET file, Paradox will check the 
file for serial numbers that match its own.  If a matching serial number is 
found Paradox will check for available user counts.  If there is an available 
user count, Paradox will increment the current number of users, and continue 
with the startup process.  If no matching serial numbers are found, Paradox 
will check for an available serial number slot.  If an available serial number 
slot is found, Paradox will place that serial number in the first free slot, 
and increment both the number of current users and the maximum number of users 
allowed.

After Paradox successfully changes the user count, it places an exclusive 
PARADOX.LCK file in a designated directory for temporary files.  If it cannot 
place that exclusive PARADOX.LCK file, Paradox will shut itself down.  After 
securing a directory for temporary files, it places a shareable PARADOX.LCK 
file in a directory with data files.  With the initialization complete, 
Paradox is now ready to open its first table.


Paradox Runtime Startup

When Paradox starts, it attempts to access the network control file specified 
in the PARADOX.SOM file.  If there is a PARADOX.NET file available, Paradox 
will open the file.  If a PARADOX.NET file is not found, Paradox will create a 
new PARADOX.NET file, place a serial number in it and continue with the 
startup process.  After opening the PARADOX.NET file, Paradox will check the 
file for serial numbers that match its own.  If a matching serial number is 
found Paradox will check for available user counts.  If there is an available 
user count, Paradox will increment the current number of users, and continue 
with the startup process.  If no matching serial numbers are found, Paradox 
will check for an available serial number slot.  If an available serial number 
slot is found, Paradox will place that serial number in the first free slot, 
and increment both the number of current users and the maximum number of users 
allowed.

After Paradox successfully changes the user count, it places an exclusive 
PARADOX.LCK file in a designated directory for temporary files.  If it cannot 
place that exclusive PARADOX.LCK file, Paradox will shut itself down.  After 
securing a directory for temporary files, it places a shareable PARADOX.LCK 
file in a directory with data files.  With the initialization complete, 
Paradox is now ready to open its first table.


Paradox Engine Startup

The Paradox Engine handles the startup process differently than Paradox.  A 
call is made to PXNetInit() specifying the location of the Paradox network 
control file.  The Engine then attempts to access the network control file 
specified by the call to PXNetInit().  If the PDOXUSRS.NET file exists and 
there is an available slot for an additional user, the Engine application 
increments the number of current users and the number of user counts 
available.  However, Windows Engine applications only increment those counts 
once for all Windows Engine applications running under the same session of 
Windows.  When running a Paradox Engine Windows application, a call is made to 
PXWinInit() which reads the location of the Paradox network control file from 
the WIN.INI file.  The location of the PDOXUSRS.NET file is written into the 
WIN.INI file using PXENGCFG.EXE.

While the Paradox Engine does not use the concept of "Private" directory, with 
the new DIRLOCK locking state, it can exclusively lock an entire directory.  
The Paradox Engine does not automatically place the directory locking file.  
You must make an explicit call to PXFileLock(), or any of the table level 
Engine function calls that would automatically place a lock on a file in order 
to test the availability of files in that directory.  Any of these function 
calls would automatically place a sharable PDOXUSRS.LCK and an exclusive 
PARADOX.LCK file in that directory.  


Conclusion

Since Paradox/Engine/ODAPI places a lock file in the directory where the 
tables are, the first locking protocol to get to that directory will own the 
directory.  If that locking protocol is Paradox 2.0 compatible, then any 
version of Paradox from 2.0 to 3.5 or Paradox Engine 1.0 - 2.0 or Engine 3.0 
in compatible locking mode will have concurrent access to the directory and 
all files in that directory.  If the first locking protocol to use that 
directory is Paradox 4.0, then only Paradox 4.0, or any Engine 3.0 application 
using standard locking mode or ODAPI will have access to the tables in that 
directory.  

---------------------------------------------------------------
Footnotes:
Quattro Pro 4.0, files dated 9/12/92 or later support both locking protocols, 
and all table formats.

Quattro Pro 4.0, files dated before 9/12/92 only support the Paradox 2.0 
locking protocol and Paradox 1.0 - 3.5 table formats.

Quattro Pro for Windows only reads and writes the Paradox 4.0 table format.  
It will not create a Paradox 4.0 table.

Locking.doc, 6th rev.   01/14/93
			
			


