diff options
Diffstat (limited to 'docs/html/xbc2.html')
-rwxr-xr-x | docs/html/xbc2.html | 151 |
1 files changed, 126 insertions, 25 deletions
diff --git a/docs/html/xbc2.html b/docs/html/xbc2.html index 72a6009..71d4585 100755 --- a/docs/html/xbc2.html +++ b/docs/html/xbc2.html @@ -2,24 +2,38 @@ <HTML> <TITLE>Xbase DBMS Chapter 2</TITLE> <BODY BGCOLOR=#FFFFFF> -<H2><p align="center">Database Overview</p></H2> -<p align="center">Chapter Updated 11/21/22</p><hr> - -The objective of this chapter is to provide information regarding how -the database files are utilized and document the various record structures. -With the exception of the brief section on the record buffer, the -information presented in this chapter is not required to use the -Xbase library. It is mainly information describing internal file -structures utilized by the Xbase routines.<br><br> - -Xbase DBF files are comprised of a variable length header record which stores -information about the file and describes -the fixed length record format, followed by a series of fixed length -data records. +<H2><p align="center">System Overview</p></H2> +<p align="center">Chapter Updated 04/28/23</p><hr> + +<br><br> +The <em>XBase64</em> library is a cross platform object oriented C++ set of classes for +accessing and manipulating the following Xbase file types:<br><br> + + +<table border=1> +<tr><th>Extension</th><th>Description</th><th>Supported by Xbase64 library?</th></tr> +<tr><td>*.DBF</td><td>Main DBF file or table name</td><td><center>Y</center></td></tr> +<tr><td>*.DBT</td><td>Verson 3 or Version 4 memo file</td><td><center>Y</center></td></tr> +<tr><td>*.NDX</td><td>Single tag index file</td><td><center>Y</center></td></tr> +<tr><td>*.MDX</td><td>Multi tag index file</td><td><center>Y</center></td></tr> +<tr><td>*.INF</td><td>ODBC file used for auto open of NDX files</td><td><center>Y</center></td></tr> +<tr><td>*.NTX</td><td>Clipper indexfile </td><td><center>Future</center></td></tr> +<tr><td>*.CDX</td><td>Fox Pro indexfile </td><td><center>Future</center></td></tr> +<tr><td>*.IDX</td><td>Fox Pro index file</td><td><center>Future</center></td></tr> +</table> + + + + +<br><br> + +DBF files are comprised of a variable length header record which stores +information about the file and describes he fixed length record format, +followed by a series of fixed length data records. <br><br> Each fixed length data record is preceded by a one byte indicator -which identifiies if the record has been deleted. If the record is +which identifies if the record has been deleted. If the record is not deleted, the indicator is a space (0x20). If deleted, the indicator contains an asterisk (0x2A). Data fields are stored in records without field separators or record terminators.<br><br> @@ -70,7 +84,6 @@ method will back out any updates to the record buffer. <br><br> - <hr> <br> <h3>Xbase Database File Header - DBF Version III and Version IV</h3> @@ -156,16 +169,8 @@ Type 4 memo fields can be used for storing BLOB (binary large object) data reliably, as the internal file structure does not rely on any special characters embedded in the data.<br><br> -A special note on storing string data in a memo field. For those users -that are new to C/C++ programming, string fields typically end with -a null (0x00) terminator character. As a general rule of thumb when using -the library, add one to the length of any string when -specifying the length of the data. This stores the null terminating byte -with the data. For example, when storing string "This is a string" -specified size should be 17, not 16. - -<h4>Technical memo file information</h4> +<h3>Technical memo file information</h3> The following info on memo fields is for the curious. It is not required @@ -261,6 +266,102 @@ is added to the free block chain. Version 3 and 4 memo fields are terminated with two contiguous 0x1A bytes of data. <br><br> <hr> + + +<h3>Block Reads</h3> + +As of release 4.1.1, the Xbase library includes functionality for reading a DBF file in blocks, rather than one record at a time.<br><br> + +This functionality can be used to improve application performance in situations where a data file is being read sequentially. +For situations where records are retrieved randomly from the file, enabling this probably won't help much. In short, this +can be turned on when accessing a file sequentially and should be left off when not processing sequentially.<br><br> + +The logic is handled internally within the library, all that is needed is to +enable it and the library handles the rest. Additionally, the block read functionality +was designed with for sequential file access and is designed with reporting in mind. +It doesn't currently have any auto locking associated with it. +<br><br> + +To enable and disable Block Reading for a DBF file, use +<em>xbDbf::EnableBlockReadProcessing()</em> +and <em>xbDbf::DisableBlockReadProcessing()</em>. +<br><br> + +<hr> +<h3>Locking Overview</h3> + +Xbase64 supports multi-user processing through file and record locks. +Record locking restricts multiple cooperating programs from simultaneously +accessing the same data and corrupting it. Without record and file locking +in a multi-user environment, simultaneous access to the data and index files +can cause the files to become inaccurate and unusable.<br><br> + +Automatic record locking is on by default in the Xbase64 library. To disable it, +use method xbXBase::DisableDefaultAutoLock() and to enable it, use method xbXBase::EnableDefaultAutoLock(). +<br><br> +Locking can also be enabled / disabled at the table level with with xbDbf::SetAutoLock().<br><br> +If autolocking is disabled and the code base is being used in a multi user environment, it is +up to the application program to verify the needed locks are set as there is no checking or +setting any locks if autolocking is turned off. It is only safe to turn off the autolocking functionality +if the library is being used in a single user environment. + +<br><br> +The current Xbase64 record locking logic is modeled after DBase (tm) V7 locking. +<br><br> + +The locking methods return either XB_LOCK_FAILED or XB_NO_ERROR. If they return +XB_LOCK_FAILED the actual reason can be found in the global variable +<em>errno</em> or function <em>perror()</em> can be executed to view the +results. +<br><br> + +The errno field may contain one of the following values if the lock was not +successful.<br><br> +<TABLE BORDER> +<TR VALIGN="BASELINE"> +<TR><TH ALIGN="LEFT">Error Code<TD>Description +<TR><TH ALIGN="LEFT">EBADF<TD>Invalid file descriptor +<TR><TH ALIGN="LEFT">EINVAL<TD>Invalid lock information or file does not support locks +<TR><TH ALIGN="LEFT">EACCESS<BR>EAGAIN<TD>Lock can not be set because it is blocked by an existing lock on the file. +<TR><TH ALIGN="LEFT">ENOLCK<TD>The system is out of lock resources, too many file locks in place. +<TR><TH ALIGN="LEFT">EDEADLK<TD>Deadlock condition +<TR><TH ALIGN="LEFT">EINTR<TD>Process was interrupted by a signal while it was waiting +</TABLE> +<br><br> + +<h3>Linux/Windows File Locking Compatibility Issue</h3> + +There is a compatibility locking issue to be aware of. Windows environments allow for the exclusive +opening of file handles and Linux/Unix platforms do not. If you are writing an application that will be +using a tool like Dbase on a Windows machine, accessing a file on a Linux/Samba configure machine, +be aware that the file could be opened in exclusive mode by DBase on the Windows system, and the same file could +be simultaneously opened with a program on the Unix box. That could cause some issues. + +<br><br> +In Unix, a program can not lock a file so another process can not access it.<br> +In Windows, a program can lock a file so another process can not access it.<br> +DBase(tm) supports routines to open files exclusively, preventing other users from opening a file.<br> +Locking on the Mac/Apple platform only works on NFS shares. It does not work with SMB shares. + +<br><h3>Samba settings</h3> + +If you will be using Samba on Linux/Unix and sharing files between Linux and Windows machines, +you will need to disable oplocks. In the smb.conf file, set:<br> +<br> +[sharename]<br> +oplocks = False<br> +level2 oplocks = False + + +<br><h3>iLockFlavor</h3> + +The library was constructed in a manner so that it could be updated to support alternate lock "flavors". +The 4.x.x library is built to mirror the DBase locking, but the structure is in place to expand to other locking +types if needed. + + +<br><br> +<hr> <p><img src="xbase.jpg"><hr> </BODY> </HTML> |