Advantage Database Server Guide

For Novell NetWare®, Windows NT®/2000®, and Windows 95®/98®/ME®

Version 6.0
March 2001
 Advantage Database Server Guide

Table of Contents

Introduction......................................................................................................... 1
Advantage Database Server Overview.........................................................................1
The Advantage Product Family ....................................................................................2
Advantage Data Architect ............................................................................................2
Installing the Advantage Database Server ....................................................... 4
System Requirements..................................................................................................4
Installing and Loading the Advantage Database Server for NetWare ...........................5
Installing and Starting the Advantage Database Server for Windows NT/2000.............6
Installing and Starting the Advantage Database Server for Windows 95/98/ME ...........9
Performing Silent Installs............................................................................................11
Modifying Configuration Parameters During Installation .............................................12
Advantage File Formats................................................................................... 13
Advantage File Formats Overview .............................................................................13
Xbase Format ............................................................................................................13
Advantage Proprietary Format ...................................................................................17
Advantage File Format Specifications ........................................................................21
Choosing a File Format..............................................................................................26
Advantage Client/Server Architecture ............................................................ 31
Client/Server Overview...............................................................................................31
Multi-User Performance .............................................................................................31
Database Stability ......................................................................................................32
Advantage ISAM File Concepts....................................................................... 34
Indexed Sequential Access Method (ISAM) Overview................................................34
Advantage ISAM File Types.......................................................................................34
Movement Operations................................................................................................35
Table Sharing Modes .................................................................................................36
Locking ......................................................................................................................36
Data Update Visibility .................................................................................................36
Filters .........................................................................................................................37
Relations (Master/Detail Relationships)......................................................................37
Types of Indexes........................................................................................................37
Index Scopes (Ranges)..............................................................................................38
Supported Expressions ..............................................................................................39
Index Scope versus Traditional Record Filters Comparison .......................................40
Advantage Database Server Features ............................................................ 42
Database Security......................................................................................................42
Advantage Locking Modes .........................................................................................44
Single Application Scalability......................................................................................46
Advantage Data Dictionary.........................................................................................46
Referential Integrity ....................................................................................................48
Encryption..................................................................................................................50
Reduced File Handle Usage ......................................................................................51
Advantage Optimized Filters ......................................................................................51
Read-Ahead Record Caching ....................................................................................55
Transaction Processing System .................................................................................56
Advantage Extended Procedures...............................................................................57
Advantage Transaction Processing System .................................................. 63
Advantage Database Server Guide

Advantage Transaction Processing System ...............................................................63

Advantage TPS Features...........................................................................................64
Advantage TPS Limitations ........................................................................................68
Advantage Database Server Configuration.................................................... 70
Advantage Database Server Configuration for NetWare ............................................70
Advantage Database Server Configuration for Windows NT/2000 .............................72
Advantage Database Server Configuration for Windows 95/98/ME............................73
Advantage Database Server Configuration Parameters for NetWare,
Windows NT/2000 and Windows 95/98/ME................................................................74
Advantage Management Information.............................................................. 85
Advantage NLM Screen .............................................................................................85
Advantage NLM Management Utility ..........................................................................86
Advantage Configuration Utility for Windows NT/2000 ...............................................89
Advantage Database Server for Windows 95/98/ME GUI ..........................................90
Advantage Management Utility...................................................................................90
Advantage Management API .....................................................................................92
Performance Factors........................................................................................ 93
General Performance Factors ....................................................................................93
Performance Factors Relative to Non-Client/Server ...................................................95
Troubleshooting and Technical Support........................................................ 97
Technical Support (U.S. and Canada)......................................................................97
www.AdvantageDatabase.com ..................................................................................98
Troubleshooting in the NetWare Environment ............................................................98
Troubleshooting in the Windows NT/2000 Environment .............................................99
Troubleshooting in the Windows 95/98/ME Environment ......................................... 101
 Advantage Database Server Guide

Introduction

Advantage Database Server Overview

The Advantage Database Server is a scalable, seamless, high-performance embedded DBMS that brings
client/server benefits to mobile, networked and Internet networked database applications. The Advantage
Database Server allows developers to work with the same easy-to-use development tools and
methodology, but replaces the PC database architecture with a distributed client/server model.

The Advantage Database Server is the key to improved database performance in network environments.
The server can be visualized as an intelligent controller that reduces competition for resources and off-
loads much of the work normally performed by each client workstation. It is responsible for all database
access, including all reading and writing of data, and lock management. Working with the network
operating system, the Advantage Database Server processes data requests and returns the information
to the network clients.

Support for NetWare, Windows NT/2000, and Windows 95/98/ME Operating

Systems
The Advantage Database Server supports the NetWare, Windows NT/2000, and Windows 95/98/ME
operating systems. The Advantage Database Server for NetWare is implemented as a NetWare Loadable
Module (NLM). An NLM is simply an executable for the NetWare operating system. The Advantage
Database Server for Windows NT/2000 operates as a Windows NT/2000 Service. The Advantage
Database Server for Windows 95/98/ME operates as an application running in the system tray.

Note The Advantage Database Server for Windows NT/2000 is a Service. It cannot be run as a standard
Windows application. See Installing and Starting the Advantage Database Server for Windows NT/2000,
for more information on Windows NT/2000 Services and how to start them.

The Advantage NLM, the Advantage Database Server Service, and the Advantage Database Server
application all act as a database server. That is, they retrieve requests for database operations to be
performed on behalf of the clients. The Advantage Database Server locates tables on the server and
processes the database operations. The result of the operation is then returned to the client across the
network, eliminating the need to send the database to the client for processing. This provides far better
concurrency control and system integrity than is otherwise available.

Traditional non-client/server applications send raw data from the server across the network to be
processed on the workstation. With the Advantage Database Server, much of the data is processed by
the Advantage Database Server on the file server. By decreasing network traffic, you increase
performance.

The Advantage Database Server integrity system ensures that database updates either run to completion
or do not begin. The Advantage Database Server will not execute partial commands. This means that the
integrity of your database no longer depends on the stability of the workstations on the network. Because
the Advantage Database Server is responsible for all database access (on behalf of the clients), it can do
a far better job of concurrency control than traditional systems, where concurrency must be synchronized
between remote workstations. Better concurrency control means better multi-user performance.

Introduction 1
Advantage Database Server Guide

The Advantage Product Family

The Advantage Database Server is the database engine that supports an entire family of Advantage
products. Brief descriptions of Advantage clients and Advantage Internet Server are provided below. For
more information, reference your client-specific Advantage documentation, your Advantage Internet
Server documentation, or visit the Advantage Web site: www.AdvantageDatabase.com.

Advantage Clients
Advantage clients can seamlessly replace existing database drivers with fully compatible Advantage
drivers. Previously developed database applications can be easily converted to access the Advantage
Database Server using customized Advantage development interfaces. Advantage clients are free and
are included on the Advantage product CD.

Available Advantage clients include native, integrated solutions for Delphi, C++ Builder, CA-Clipper, CA-
Visual Objects, and Microsoft FoxPro. Windows development platforms can also access the Advantage
Database Server via the Advantage Client Engine API. Also available is the Advantage ODBC Driver and
the Advantage OLE DB Provider.

Advantage Internet Server

The Advantage Internet Server is a simple, non-HTML solution that provides data access via the Internet
using existing Advantage applications. With the combination of Advantage clients, the Advantage Internet
Server, and the Advantage Database Server, remote users can experience the same security, integrity,
and performance experienced on the corporate LAN while accessing data remotely using the Internet as
a Virtual Private Network. The Advantage Internet Server is sold separately.

Advantage Data Architect

The Advantage Data Architect (ARC) is a tool designed to assist you in efficiently developing and
maintaining Advantage database applications.

Development
While developing your database application ARC enables you to:
• Import other table types (such as Paradox, Btrieve, Access, etc.) to Advantage compatible tables
• Create and maintain Advantage Data Dictionaries
• Create tables and indexes
• Restructure existing tables
• Encrypt/decrypt tables and/or dictionaries
• Test filters, scopes/ranges, and lookups
• Generate and test Advantage StreamlineSQL queries using a visual query designer
• Test ODBC SQL queries
• Generate code to automatically create tables and indexes using the Advantage Tables to Code
Generator

Configuration
When setting up your database application ARC enables you to:
• Test the client's environment to prevent problems when connecting to the Advantage Database
Server
• Create aliases similar to those used by the Borland Database Engine

Management
After the database is running, ARC enables you to:

2 Introduction
 Advantage Database Server Guide

• Manage data with functions such as reindexing, packing tables, restructuring and repairing tables
• Manage Data Dictionaries with the Advantage Database Administrator Tool
• Manage Advantage Database Server activity with the Advantage Management utility
• Execute maintenance tasks from within a transaction

Introduction 3
Advantage Database Server Guide

Installing the Advantage Database Server

System Requirements

Networks
Novell NetWare 4 or later
Microsoft Windows NT 4
Microsoft Windows 95
Microsoft Windows 98
Microsoft Windows ME
Microsoft Windows 2000

Network Protocols (on the Server)

IPX with NetWare 4 or newer, Windows NT, Windows 2000, Windows 95, Windows 98, and Windows ME
IP with NetWare 5 and newer, Windows NT, Windows 2000, Windows 95, Windows 98, and Windows ME
File Server Processors
Multiple processors supported with NetWare 5 and newer, Windows NT, and Windows 2000
Client Operating Systems
Windows 3.1x, Windows 95, Windows 98, Windows ME, Windows NT, Windows 2000, DOS 3.3 or higher
Client database applications developed with supported Advantage clients

Client Development Platforms

Delphi (via native components, OLE DB Provider, ODBC Driver, or API)
C++Builder (via native components, OLE DB Provider, ODBC Driver, or API)
Visual Basic (via OLE DB Provider, ODBC Driver, or API)
Access 97/2000 (via OLE DB Provider, ODBC Driver, or API)
Visual C++ (via OLE DB Provider, ODBC Driver, or API)
Visual FoxPro (via OLE DB Provider, ODBC Driver, or API)
Visual Objects (via RDD, OLE DB Provider, ODBC Driver, or API)
Clipper (via RDD)
Xbase Table Formats Supported
Clipper-compatible DBF, FoxPro-compatible DBF
Xbase Index File Formats Supported
Clipper-compatible NTX, FoxPro-compatible CDX, FoxPro-compatible IDX
Xbase Memo File Formats Supported
Clipper-compatible DBT, FoxPro-compatible FPT
Proprietary Advantage Table Format Supported
ADT
Proprietary Advantage Index File Format Supported
ADI
Proprietary Advantage Memo File Format Supported
ADM
Licensing
The Advantage Database Server is sold on a per-server basis with User Options to provide concurrent
users up to the maximum specified. Each PC workstation running one or more Advantage applications is
considered a user.

4 Installing the Advantage Database Server

 Advantage Database Server Guide

Installing and Loading the Advantage Database Server for NetWare

Installing the Advantage NLM for NetWare

Note You must have administrative privileges to install the Advantage Database Server.

1. Proceed through the introductory windows that appear on the screen.

2. Select the version of NetWare the Advantage Database Server is to be installed upon. It is important
that correct version of NetWare be selected. If "NetWare Version 5.x or Newer" is selected, the
Advantage Database Server for NetWare 5 will be installed. This Advantage NLM has support for IP
and multiple processors. This NLM will not load on a NetWare 3.x or 4.x server.

3. Once the Advantage Database Server files have been copied to the NetWare server, the Product
Information window prompts you to enter the Advantage serial number, validation code or
authorization code, and the name of the registered owner. Reference the Advantage Database
Server Serial Number ID Card included with the product to find your serial number and validation
code or authorization code.

4. International Advantage version only: To properly perform string comparisons with local
languages, Advantage provides OEM/localized character sets to match your country's language
requirements. If your Advantage application uses OEM/localized character sets, select the character
set which matches your Advantage client applications. Selecting a specific OEM/Localized character
set for all Advantage installs (including Advantage Local Server) will guarantee the OEM/Localized
character sets used by all Advantage applications will be the same. If your Advantage applications
use ANSI character sets only, select Next.

5. To properly perform string comparisons when using ANSI collation, Advantage provides ANSI
character sets to match your country's language requirements. If your Advantage application uses
ANSI character sets, select an ANSI character set to be used on the Advantage Database Server. If
<DEFAULT ON MACHINE> is chosen, the currently configured ANSI character set on the installing
workstation will be used. If you do not wish to use the ANSI character set that is currently active, this
setting can be used to select a specific character set. Selecting a specific ANSI language for all
Advantage installs (including Advantage Local Server) will guarantee the ANSI character sets used
by all Advantage applications will be the same. Note that the USA version of the Advantage Database
Server supports English(American), English(Canadian), and French Canadian only. If a different
ANSI language is desired, a non-USA version of the Advantage Database Server must be installed.

Loading the Advantage NLM

The Advantage NLM must be loaded before applications can run using the Advantage Database Server.
Once the Advantage Database Server files are installed, you can load the Advantage NLM into file server
memory any time the file server is running.

To load the Advantage NLM using the default configuration, enter the following from the NetWare system
console:

LOAD SYS:\ADS\ADS.NLM

When the NLM is loaded, the Advantage NLM screen is displayed. Once the Advantage NLM screen
appears, the Advantage NLM is ready to accept client commands.

Installing the Advantage Database Server 5

Advantage Database Server Guide

Unloading the Advantage NLM

To unload the Advantage NLM, follow one of these two steps:

1. If the Advantage NLM screen is displayed, press the <F5> key. You will be prompted to complete the
unloading of the NLM.
2. If the Advantage NLM screen is not displayed, enter the following from the system console at the ':'
prompt:

UNLOAD ADS.NLM

You can unload the Advantage NLM from the file server at any time. However, if the Advantage NLM is
unloaded while users are active, there is the potential for database corruption, because tables and index
files may be only partially updated. Verify that there are no users active when unloading the Advantage
NLM. After the NLM is unloaded, all resources are returned to the NetWare operating system.

Installing and Starting the Advantage Database Server for Windows

NT/2000

Installing the Advantage Database Server Service for Windows NT/2000

Note You must have administrative privileges to install the Advantage Database Server.

1. Proceed through the introductory windows that appear on the screen.

2. Once the Advantage Database Server files have been copied, the Product Information window
prompts you to enter the Advantage Database Server serial number, validation code or authorization
code, and the name of the registered owner. Reference the Advantage Database Server Serial
Number ID Card included with the product to find your serial number and validation code or
authorization code. Radio buttons exist to choose the Advantage Database Server Service Startup
option. If you are unsure of which startup option to choose, the default Automatic is recommended.

3. International Advantage Database Server version only: To properly perform string comparisons
with local languages, Advantage provides OEM/localized character sets to match your country's
language requirements. If your Advantage application uses OEM/localized character sets, select the
character set that matches your Advantage client applications. Selecting a specific OEM/Localized
character set for all Advantage installs (including Advantage Local Server) will guarantee the
OEM/Localized character sets used by all Advantage applications will be the same. If your Advantage
applications use ANSI character sets only, select Next.

4. To properly perform string comparisons when using ANSI collation, Advantage provides ANSI
character sets to match your country's language requirements. If your Advantage application uses
ANSI character sets, select an ANSI character set to be used on the Advantage Database Server. If
<DEFAULT ON MACHINE> is chosen, the currently configured ANSI character set will be used. If
you do not wish to use the ANSI character set that is currently active, this setting can be used to
select a specific character set. Selecting a specific ANSI language for all Advantage installs (including
Advantage Local Server) will guarantee the ANSI character sets used by all Advantage applications
will be the same. Note that the USA version of the Advantage Database Server supports
English(American), English(Canadian), and French Canadian only. If a different ANSI language is
desired, a non-USA version of the Advantage Database Server must be installed.

6 Installing the Advantage Database Server

 Advantage Database Server Guide

To start the Advantage Database Server Service, you must start the "Advantage Database Server"
service from the Service Control Manager. See the Starting and Stopping the Advantage Database
Server Service section in Understanding Windows NT/2000 Services for more information on how to start
the Advantage Database Server for Windows NT/2000.

Uninstalling the Advantage Database Server for Windows NT/2000

To uninstall the Advantage Database Server for Windows NT/2000, perform the following steps:

• Stop the Advantage Database Server Service

• Run the ADS Service Uninstall utility
• Complete the uninstall via the Windows "Add/Remove Programs" functionality.

To stop the Advantage Database Server Service:

1. Enter the Service Control Manager via the Services icon in the Control Panel Folder.
2. Select Advantage Database Server and click Stop.

To run the ADS Service Uninstall utility:

Double click on the "ADS Service Uninstall" icon located in the Advantage Database Server folder. This
Advantage Database Server Service uninstall utility will remove the Advantage Database Server Service
from the Service Control Manager. This uninstall utility will not fully uninstall the Advantage Database
Server from the computer, however.

To complete the uninstall of the Advantage Database Server:

1. Double click on the "Add/Remove Programs" icon in the Control Panel folder.
2. Click Advantage Database Server.
3. Click the "Add/Remove..." button.

Understanding Windows NT/2000 Services

In Windows NT/2000, many server-side programs act as a service. Unlike regular applications, services
run in the background providing application support and have no user interface of their own. Most
services can be started, stopped, paused, and continued. Windows NT/2000 services are controlled
through the Windows NT/2000 Service Control Manager. The Service Control Manager lists all installed
services and their current status.

To access the Service Control Manager with Windows NT 4.0, open the Control Panel folder and double
click the Services icon. To access the Service Control Manager with Windows 2000, click the Start
button, select Programs, Administrative Tools, Services, and finally double click on the Services icon.
Among the information provided by the Service Control Manager is the following:

• Server status—relates the current status of the service (started, stopped, or paused)
• Startup options—allows you to select the startup type for the selected service (automatic or manual)
• Startup parameters—the startup parameters box allows you to specify startup parameters to a
particular service

Advantage Database Server Service

The Advantage Database Server was designed as a service to provide the most robust and safest
database management possible. As a service, Advantage has better control over how and when the
program is started and shut down. For example, if the startup type Automatic was selected during

Installing the Advantage Database Server 7

Advantage Database Server Guide

installation of the Advantage Database Server, the Advantage Service will automatically start when the
server comes up again after being shut down. This provides a benefit over regular applications because it
does not require a user to log in to get the Advantage Service up and running again after a power failure
or other unexpected shut down.

Starting and Stopping the Advantage Database Server Service

The Advantage Database Server Service must be started before applications can run using the
Advantage Database Server. Administrative privileges are required to stop a service. The pause and
continue features are not available with the Advantage Database Server Service. Follow the steps below
to start and stop the Advantage Database Server Service for Windows NT 4.0.

1. Open the Control Panel folder.

2. Double click the Services icon.
3. Choose the Advantage Database Server from the list provided.
4. Click either the Start or Stop button as required.

Follow the steps below to start and stop the Advantage Database Server Service for Windows 2000.

1. Click the Start button on the taskbar.

2. Select Programs, Administrative Tools, and Services.
3. Choose the Advantage Database Server from the list provided.
4. Click either the Start or Stop button as required.

Using Windows NT/2000 Event Logging

Windows NT/2000 event logging provides a centralized way for applications and services to record
events such as when a service was stopped or started as well as error conditions. The Windows NT/2000
Event Viewer provides a standard user interface for viewing logged events. There are three types of
event logs:

• System Log—tracks Windows NT/2000 system information

• Security Log—tracks events triggered by security violations
• Application Log—tracks events written by an application

The Event Viewer is accessed through the Administrative Tools group/folder. Select the type of log file
you want to view (System, Security, or Application) from the Log menu option. Double click on any event
in the events list to view event details.

Event Logging and the Advantage Database Server Service

Information, warnings and errors pertaining to the Advantage Database Server Service are recorded in
the Event Application Log. Information messages are used to record when the Advantage Database
Server Service was started or stopped. Advantage Service warnings alert users of recoverable problems.
Errors, however, are used to display non-recoverable conditions that are likely to cause a service failure.

The Advantage Database Server Service also maintains an error log for additional, non-system related
Advantage Database Server errors. By default, the error log is located in the root directory of the drive
where the Advantage Database Server is installed. The location of this log is configurable. For more
information about the Advantage Database Server error log, see Troubleshooting in the Windows
NT/2000 Environment.

8 Installing the Advantage Database Server

 Advantage Database Server Guide

Installing and Starting the Advantage Database Server for Windows

95/98/ME

Installing the Advantage Database Server for Windows 95/98/ME

1. Proceed through the introductory windows that appear on the screen.

2. Once the Advantage Database Server files have been copied, the Product Information window
prompts you to enter the Advantage Database Server serial number, validation code or authorization
code, and the name of the registered owner. Reference the Advantage Database Server Serial
Number ID Card included with the product to find your serial number and validation code or
authorization code. Radio buttons exist to choose the Advantage Database Server Startup option. If
you are unsure of which startup option to choose, the default Automatic is recommended.

3. International Advantage version only: To properly perform string comparisons with local
languages, Advantage provides OEM/localized character sets to match your country's language
requirements. If your Advantage application uses OEM/localized character sets, select the character
set that matches your Advantage client applications. Selecting a specific OEM/Localized character
set for all Advantage installs (including Advantage Local Server) will guarantee the OEM/Localized
character sets used by all Advantage applications will be the same. If your Advantage applications
use ANSI character sets only, select Next.

4. To properly perform string comparisons when using ANSI collation, Advantage provides ANSI
character sets to match your country's language requirements. If your Advantage application uses
ANSI character sets, select an ANSI character set to be used on the Advantage Database Server. If
<DEFAULT ON MACHINE> is chosen, the currently configured ANSI character set will be used. If
you do not wish to use the ANSI character set that is currently active, this setting can be used to
select a specific character set. Selecting a specific ANSI language for all Advantage installs (including
Advantage Local Server) will guarantee the ANSI character sets used by all Advantage applications
will be the same. Note that the USA version of the Advantage Database Server supports
English(American), English(Canadian), and French Canadian only. If a different ANSI language is
desired, a non-USA version of the Advantage Database Server must be installed.

5. Due to limitations in Windows 95/98/ME, the Advantage Database Server is only able to support one
network protocol at a time. In the Select Protocol window, select whether the Advantage Database
Server for Windows 95/98/ME will use IP or IPX for communication between Advantage clients.

Windows 95/98/ME and Non-USA NT/2000 Software Protection

Overview
Both the USA and non-USA versions of the Advantage Database Server for Windows 95/98/ME and the
non-USA version of the Advantage Database Server for Windows NT/2000 are enabled with software
protection. The software protection is handled completely by software without the use of a hardware key.
Evaluation servers, that use authorization codes, do not require registration. Only purchased servers with
validation codes require registration.

A purchased server must be registered within four days of the time when the server is first executed. At
midnight of the fourth day, the unregistered server will disconnect all users and shut itself down. For
Windows 95/98/ME, an unregistered server displays the days left before registration is required on a
dialog screen displayed at startup and on the top right corner of the Advantage Database Server GUI. For
Windows NT/2000, an unregistered server displays the days left before registration is required on a dialog
screen displayed at startup of the Advantage Configuration utility (ADS_CFG.EXE) and on the top right

Installing the Advantage Database Server 9

Advantage Database Server Guide

corner of the utility. Re-installing the server on the same machine will not issue additional pre-registration
days.

Registration
To register, click the Register button, which for Windows 95/98/ME is on both the startup dialog screen
and on the Advantage Database Server GUI. For Windows NT/2000, the Register button is on the startup
dialog screen when the Advantage Configuration utility (ADS_CFG.EXE) is started and on the Advantage
Configuration utility screen itself. A register form is displayed which will ask for registration information.
Your information will not be sold or given to any other company without your permission. Be sure to
specify your e-mail address especially if you want to be notified of Advantage updates and new product
releases. When you click Continue, registration will occur through the Internet. If any errors occur, you
will have the option to register via e-mail, by phone, or by running a separate utility on a machine that is
connected to the Internet.

To register through e-mail, click Use E-mail and the e-mail dialog will be displayed. Create a new e-mail
message using your e-mail client. Copy the text in the "To…", "Subject:", and "Message Body:" on the
dialog screen to the corresponding sections in the new mail message. Note: the e-mail does not need to
be sent from the same machine that the Advantage Database Server is installed on. After all three
sections have been copied to the new e-mail message, send the e-mail. A response with the activation
code should only take a few minutes. Click Enter Activation Code and enter in the activation code
returned in the e-mail. Click on Apply to activate your license.

To register by phone, click Call Advantage and a dialog will be displayed containing phone numbers and
office hours. You can either call Advantage directly or an Advantage distributor. Click Distributors'
Phone Numbers for a list of distributors' names, location, and phone numbers. You will be asked for the
Serial Number, Validation Code, and Site Code that are all displayed on this dialog screen. Click Enter
Activation Code to enter the activation code and register the product.

To register using a different machine that is connected to the Internet, use the Advantage User
Registration utility (USERREG.EXE). This utility can be used by developers to register customers who do
not have Internet access. This utility, along with a Help file in text format (ADSREG.TXT), is installed with
the Advantage Database Server. See ADSREG.TXT for further instructions on using this utility.

All licenses are unlimited licensed that is not limited by days or runs. The server may be copied or moved
to any location on the machine without affecting the license.

Transferring a License
The software license locks the Advantage Database Server to one particular machine. However, the
license may be transfer to another machine. To transfer the license to another machine, install the
Advantage Database Server on the destination machine. Start the Advantage Database Server on the
destination machine, click Transfer License In on the dialog screen. Specify a drive path in the location
provided on the dialog screen. You will most likely specify "A:\” but a network drive shared by both
machines will also work. Start the licensed version of the Advantage Database Server. Select the
Transfer License tab on the Advantage Database Server GUI. Click Transfer License to Diskette and
specify the location of the files created by the destination machine. Click Continue to transfer the license
from this machine to the specified location. On the destination machine, specify the location of the license
files in the provided dialog screen. Click Continue to transfer the license in.

10 Installing the Advantage Database Server

 Advantage Database Server Guide

Troubleshooting/Losing a License
Problems can occur by losing a license, software authorization checking, or other general errors.

• Losing a License—A license can be lost by deleting the license file located in the System directory,
hard-drive crashing, or other problems. A license can only be granted once through the Internet or by
e-mail to the e-mail server. In these cases, you will need to contact Advantage or an Advantage
distributor directly to get another authorization code. Execute the steps above for licensing the
Advantage Database Server. When the error message occurs saying you already have been granted
a license, click Call Advantage to get the serial number, validation code, and the new Site Code. You
can either call or send e-mail to [email protected]. If you send e-mail, be sure to
include the serial number, validation code, and site code in your message.
• If you want to update your customer information in the database, call advantage or send email to
[email protected]. Be sure to include your serial number in your e-mail.
• When using a non-registered server, changing the system clock back more than a few hours will
cause the errors to occur. Set the time back to its original state and restart the server.
• When using a non-registered server, changing the system clock forward will not cause errors but it
will decrease the amount of time you have to register the product.
• A -1 "The program file could not be located." error occurs. Create a file named LICENSE.TXT in the
System directory. This file can be a zero byte file. Start the Advantage Database Server again.
• Errors occur that say a library or file is missing. Some Dynamic link libraries (DLLs) might have
deleted from the C:\Advantage directory. Replace the files or re-install the Advantage Database
Server. Note that re-installing the server will not invalidate your software license.
• For all other errors, contact Advantage Support with the error message.

Performing Silent Installs

The Advantage client and server installs can be executed with no install windows being displayed. This is
useful when calling the Advantage install from your own install. It can also be used so your customers are
not required to input information such as paths or serial numbers.

Advantage Database Server Installs

The Advantage Database Server installs read information in the SETUP.INI file. If all the information
needed to install the servers, such as paths, serial number, validation code, etc, is contained in
SETUP.INI then no setup windows will be displayed. If a path or serial number is incorrect or not
specified, a window will be displayed asking the user for the information. See the SETUP.INI file on the
install disk to see what information is needed and it's effect on the install. For Windows NT/2000 and
Windows 95/98/ME installs, also see Modifying Configuration Parameters During Installation.

Advantage Client Installs

The Advantage client installs can install the Advantage clients silently by using an InstallShield option.
You must first create an install log file that tells the install what options to use for each selection. To do
this, launch the install with the "SETUP.EXE -r" command line parameter and complete the install with the
desired selections. This will create a log file called SETUP.ISS in the C:\WINNT for Windows NT/2000 or
C:\Windows for Windows 95/98/ME. Put this file in the same location as the install files. Now you can
execute the silent install by running "SETUP.EXE -s" and the selections in the SETUP.ISS file are used.
SETUP.ISS is a text file that you can now edit if you want to change install settings without re-running the
install. An example of where this could be useful is for prompting the user for the install path using your
own install program and writing the changes in the SETUP.ISS file. Now when the "SETUP.EXE -s" is
called, the Advantage files will be installed in the new location.

Installing the Advantage Database Server 11

Advantage Database Server Guide

Note In most cases, you would not want to run the Advantage client installs at your customer's site. It is
more likely that you would install a few selected Advantage DLLs along with your application using your
own installation program.

Modifying Configuration Parameters During Installation

The configuration parameters of the Advantage Database Server for Windows NT/2000 or the Advantage
Database Server for Windows 95/98/ME can be modified during installation. This is useful when re-
distributing the Advantage Database Server with your application. Modifying parameter values, such as
the file locations, adds consistency when deploying the Advantage Database Server with your application.
Most of the other parameters do not need to be altered from their default values.

You will need to create an ADS_CFG.REG file by installing the Advantage Database Server and setting
the parameter's values as desired. For the Advantage Database Server for Windows NT/2000, execute
REGEDIT.EXE and select the folder
\\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Advantage\Configuration. For the
Advantage Database Server for Windows 95/98/ME, execute REGEDIT.EXE and select the folder
\\HKEY_LOCAL_MACHINE\SOFTWARE\Extended Systems\ADS\Configuration. Export the configuration
settings by selecting the "Registry" menu item and select "Export Registry File...". Name the file
ADS_CFG.REG. Copy this file to the last diskette of the Advantage Database Server install. This registry
file is executed before the installation program finishes. If the file is executed, a message box will display
a message stating that the registry changes have been made. The message box will also display during a
silent install.

12 Installing the Advantage Database Server

 Advantage Database Server Guide

Advantage File Formats

Advantage File Formats Overview

Advantage supports three file formats. Two of the formats are an Xbase format, and an Advantage
proprietary format.

The two Xbase file formats that Advantage supports are CA-Clipper-compatible file types and FoxPro-
compatible file types. The CA-Clipper-compatible file format consists of DBF tables, NTX index files, and
DBT memo files. The FoxPro-compatible file format consists of DBF tables, CDX and IDX index files, and
FPT memo files. The Advantage Xbase file formats are fully compatible with non-Advantage database
drivers that support CA-Clipper-compatible and FoxPro-compatible file formats. For more information
about the Xbase file formats supported by Advantage, see Xbase Format.

The Advantage proprietary file format is only usable by Advantage applications. The Advantage
proprietary format is a flat-file, record-based file format, but is not an Xbase format. The Advantage
proprietary file format cannot be read by any other Xbase database driver (such as FoxPro or CA-
Clipper), support many features that are not possible in Xbase formats, and is fully optimized for use by
Advantage. The Advantage proprietary format consists of ADT tables, ADI index files, and ADM memo
files. For more information about the Advantage proprietary file format, see Advantage Proprietary
Format.

There are many reasons why you may choose to use an Advantage Xbase file format or an Advantage
proprietary file format. For most developers converting to Advantage from the Paradox file format, you
will want to use the Advantage proprietary file format. For more information on choosing between an
Advantage file format, see Choosing a File Format.

To view information all of the low level Advantage file format specifications and data types, see
Advantage File Format Specifications.

Xbase Format

Xbase File Types

Table (DBF)
The Advantage Database Server supports standard Xbase DBF tables that are compatible with CA-
Clipper DBF tables, Microsoft FoxPro DBF tables, and dBASE III+ DBF tables. The maximum DBF field
name length is 10 bytes and may only contain the letters 'a'-'z' and 'A'-'Z', digits '0'-'9', and the underscore
'_' character. The maximum number of records in a DBF table is 2 billion.

The maximum DBF table size is 4 GB.

Index Files (CDX, IDX, NTX)

Single Order Index Files (IDX, NTX)
The Advantage Database Server supports single order Xbase index files in the IDX and NTX formats.
The syntax to build these two index file types is identical. Only the internal file formats are different. IDX
index files are a FoxPro defined index format while NTX index files are a CA-Clipper defined format.

Advantage File Formats 13

Advantage Database Server Guide

The index format is determined by the database driver used in your application. For example, the
Advantage NTX driver will build NTX indexes. For IDX indexes, use the Advantage CDX driver.

IDX index files save disk space and will increase the speed of an operation when accessing large data
sets. Key data is stored in a compressed format. An IDX index can be up to 90% smaller than an
equivalent NTX index. The amount of compression depends on the number of duplicate keys, trailing
blanks in the character keys, and blank keys in the index.

The maximum IDX or NTX file size is 4 GB.

Multiple Order (Compound) Index Files (CDX)

The Advantage Database Server supports multiple order (compound) Xbase index files in the CDX
format. CDX index files are a FoxPro defined index format. A "tag" is a single index order within a CDX. A
tag is essentially identical to a single order IDX index file and supports all of the same features. Once a
compound index file is opened, all tags contained in the file are automatically updated as the records are
changed. By default, the first tag in the compound index file (in order of creation) is the active tag when
the index file is explicitly opened. A tag name in a CDX index file is limited to 10 characters in length and
may only contain the letters 'a'-'z' and 'A'-'Z', digits '0'-'9', and the underscore '_' character.

Structural CDX
A structural CDX is also known as an "auto-open" index file. A CDX is considered a "structural" index file
when the index file has the same base name and resides in the same directory as the table. The
structural CDX will be opened automatically when the table is opened and cannot be closed as long as
the table is open.

Non-structural CDX
All CDX index files that do not have the same base file name as the corresponding table is considered
"non-structural" and will not be automatically opened when the table is opened.

The maximum CDX file size is 4 GB.

Memo Files (DBT, FPT)

Advantage stores data for Xbase memo fields in DBT and FPT memo file formats depending on which
Advantage database driver was used to open the corresponding table. When using the Advantage NTX
driver, DBT memo files are supported. For FPT memos, the Advantage CDX driver must be used.

The maximum Xbase memo file size is 4 GB.

DBT Memo Files

DBT memo files are assigned fixed storage block sizes of 512 bytes. These storage blocks are assigned
each time a new entry is made into the file. If anywhere from 1 to 511 bytes of memo data is stored, a
single 512-byte block in the memo file will contain the data. If 512 to 1023 bytes of data are stored, two
consecutive 512-byte blocks in the memo file will contain the data. Since the blocks are large, DBTs often
contain much empty, wasted space. An end-of-file marker (ASCII 26) is used to mark the end of the
memo entry.

FPT Memo Files

Advantage FPT memo files have a default storage block size of 64 bytes. The block size is configurable
to allow you to define block sizes more adequately suited to your application. Valid memo block sizes are
in the range 33-16384. The first block in each consecutive section of memo blocks containing data for the
same memo field contains an 8-byte header. If anywhere from 1 to 56 bytes of memo data is stored, a
single 64-byte block in the memo file will contain the data. If 57 to 120 bytes of data are stored, two
consecutive 64-byte blocks in the memo file will contain the data. As you can see, FPT memo files are
much more efficient at memo data storage than are DBT memo files. An FPT stores the length of the

14 Advantage File Formats

 Advantage Database Server Guide

memo entry in the file, rather than using an end-of-file marker. Therefore, retrieval of FPT memo data is
also faster than retrieval of DBT memo data.

FPT memo files keep a "free block" list in its header. This list indicates which blocks within the file have
been freed. An abandoned block will be reused before adding a new block to the bottom of the FPT file.
DBT memo files have no concept of a "free block" list. With DBTs, any memo blocks that are no longer
used are lost forever and never reused, unless data is Packed. See your Advantage client-specific
documentation for more information on Pack operation.

DBT versus FPT Memo Block Usage Example

If the word "Kayak" is stored in a memo field in a DBT memo file, that five-byte word by itself uses 512
bytes. If that memo field information is deleted from the record (in other words, store an empty string ("")
in the memo field), those 512 bytes are not deleted from the memo file. If you add another 600 characters
to the memo field, they no longer fit in one block. The DBT memo file abandons the block (unless it was
the last block) and moves all 605 bytes to two new 512-byte blocks at the bottom of the memo file. The
old 512-byte block remains unused.

An FPT memo file stores the word "Kayak" in a 64-byte memo block. If the memo field information in that
record is deleted, the 64-byte block in the memo file is not abandoned. It is added to the FPT "free list" to
be used again. If an additional 600 characters are added to the memo field, the FPT memo file finds and
uses 10 contiguous 64-byte memo blocks in the "free list" to store the new memo data.

Note If you are using FPT memo files with a block size of 32 or less, and you created the FPT file with the
SuccessWare SIXCDX RDD for CA-Clipper, the DBFCDX RDD for CA-Clipper 5.3, or the SDE2 SDEFOX
RDE, Advantage will not be compatible with that FPT file. Memo corruption is possible if these FPTs are
used with Advantage. Advantage uses the same memo block size strategy as FoxPro.

Supported Xbase Data Types

Standard DBF Table Data Types

The following are standard field data types available in DBF tables. The length indicates the amount of
data stored in the record image. For fields that include memo file storage, see the description for the
amount of data that can be stored.

Type Length Decimals Description

Character 1 to N/A Fixed length character field that is stored entirely

65534 in the table.

Numeric 1 to 32 0 to Length- Fixed length (exact representation) numeric.

2
Date 8 N/A 8-byte date field in the form of CCYYMMDD.

Logical 1 N/A 1-byte logical (boolean) field. Recognized values

for True are '1', 'T', 't', 'Y', and 'y'.

Memo 10 or N/A Variable length memo field. Up to 65530 bytes can

4 be stored in a memo field. Visual FoxPro memo
fields require 4 bytes in the record image, while
standard DBF memo fields require 10 bytes. The
memo data is actually stored in a separate file,
called a memo file, to reduce table bloat.

Advantage File Formats 15

Advantage Database Server Guide

Extended DBF Table Data Types

The following are extended field data types available in DBF tables. The extended data types are non-
standard DBF extensions. Non-Advantage applications that read DBF tables may not be able to open and
read tables that have extended data types. Visual FoxPro will recognize double, integer, general, and
picture fields.

Type Length Decimals Description

Double 8 0-20 8-byte IEEE floating point value in the range

1.7E +/-308 (15 digits of precision). The
decimal value affects NTX indexes and the
use of the field in expressions. It does not
affect the precision of the stored data. If the
length is given, it will be ignored. For
example, "salary, double, 10, 2" and "salary,
double, 2" produce the same field.

Integer 4 N/A 4-byte long integer values from -

2,147,483,648 to 2,147,483,647.

ShortDate 3 N/A 3-byte date field. This type supports the

same range of dates as a standard date field.

Image 10 N/A Binary image data. The size of each field is

limited by machine resources. The binary
image data is actually stored in a separate
file, called a memo file, to reduce table bloat.
Updating Image fields within a transaction is
not currently supported.

Binary 10 N/A Binary data. The size of each field is limited

by machine resources. The binary data is
actually stored in a separate file, called a
memo file, to reduce table bloat. Updating
Binary fields within a transaction is not
currently supported.

General 10 or 4 N/A Binary OLE data. The size of each field is

limited by machine resources.

Picture 10 or 4 N/A Binary image data. The size of each field is

limited by machine resources.

Xbase Unique Indexes

An Xbase index order created with the "unique" property will only include records that are referenced by
unique values. If two records result in the identical key value, then only one of the records will be
referenced by the index. The second is simply never added, and no error is reported. If the record (of the
two with identical key values) referenced by the unique index is modified such that the key value
changes, that index key will be removed from the index, but the other record with the identical key value
will NOT be added to the unique index. Therefore, no key will be referencing the unique record in the
index. This is the traditional Xbase behavior of the "unique" property in Xbase indexes.

16 Advantage File Formats

 Advantage Database Server Guide

Xbase Conditional Indexes

Conditional indexes are index orders that allow you to view only those data records that meet a pre-
defined condition. Conditional indexes include only those records that satisfy a given filter expression.
The conditional index expression may be any valid expression that evaluates to a logical value.
Conditional index expression text lengths are limited depending on which type of index is being built. The
table below shows the maximum conditional index expression text length for each conditional index type.

Index Conditional Expression Length

NTX 256 bytes
IDX 512 bytes*
CDX 512 bytes*

* For IDX and CDX indexes, the total length of the key expression text and conditional expression text
combined must not exceed 512 characters, including an extra byte for each expression as a null
terminator.

Xbase Deleted Records

If a delete record operation is performed on a record in a DBF table, the record is not physically removed
from the table. Nor is the record logically removed from the table. The record is instead "marked for
deletion". Optionally, records marked for deletion can still be visible to the application. Records marked
for deletion can also be "un-deleted", or "recalled" as it is referred to in Xbase terminology. Thus, the
deletion status of a record is nothing more than a filter. If an application is written to allow records marked
for deletion to be visible (which is the default), then the record deletion status is irrelevant. If an
application is written to ignore records that are marked for deletion, then those records marked for
deletion have effectively been filtered from visibility. If the Pack operation is performed on a table, then
and only then will records marked for deletion be physically removed from the table.

Advantage Proprietary Format

Advantage Proprietary File Types

Table (ADT)
The Advantage Database Server supports a proprietary ADT table. The maximum ADT field name length
is 128 bytes and may contain any character value except 0 (NULL), ';' (a semi-colon), or ',' (a comma).

The current maximum number of records in an ADT table is 2 billion. When Advantage Database Server
code limitations are resolved in a future release, the maximum number of records in an ADT table will be
9,223,372,036,854,775,807 records (i.e., 2 ^63 records).

Advantage Database Server for Windows NT/2000

If the NTFS file system is used the maximum table size is 16 exabytes (i.e., 18,446,744,073,709,551,616
bytes).

If the FAT32 file system is used the maximum table size is 4 gigabytes (i.e., 4,294,967,296 bytes).

Advantage Database Server for Windows 95/98/ME

The maximum table size is 4 gigabytes (i.e., 4,294,967,296 bytes).

Advantage Database Server for NetWare

Due to low-level NetWare API limitations the maximum table size is 4 gigabytes (i.e., 4,294,967,296
bytes).

Advantage File Formats 17

Advantage Database Server Guide

Index Files (ADI)

The Advantage Database Server supports a proprietary multiple order (compound) ADI index file. A "tag"
is a single index order within an ADI. ADI index orders save disk space and will increase the speed of an
operation when accessing large data sets. Key data is stored in a compressed format. Once an ADI index
file is opened, all tags contained in the file are automatically updated as the records are changed. By
default, the first tag in the ADI index file (in order of creation) is the active tag when the index file is
explicitly opened. A tag name in an ADI index file is limited to 128 characters in length and may contain
any character value except 0 (NULL), ';' (a semi-colon), or ',' (a comma).

Auto-Open ADI
An ADI is considered an "auto-open" index file when the index file has the same base name and resides
in the same directory as the table. The auto-open ADI will be opened automatically when the table is
opened and cannot be closed as long as the table is open.

Non-Auto-Open ADI
All ADI index files that do not have the same base file name as the corresponding table is considered
"non-auto-open" and will not be automatically opened when the table is opened.

Advantage Database Server Service for Windows NT/2000

If the NTFS file system is used the maximum ADI index file size is 2 terabytes (i.e., 2,199,023,255,552
bytes).

If the FAT32 file system is used the maximum ADI index file size is 4 gigabytes (i.e., 4,294,967,296
bytes).

Advantage Database Server for Windows 95/98/ME

The maximum ADI index file size is 4 gigabytes (i.e., 4,294,967,296 bytes).

Advantage Database Server for NetWare

Due to low-level NetWare API limitations the maximum ADI index file size is 4 gigabytes (i.e.,
4,294,967,296 bytes).

Memo Files (ADM)

Advantage stores data for memo fields in a proprietary ADM memo file format. ADM memo files have a
default storage block size of 8 bytes. The block size is configurable to allow you to define block sizes
more adequately suited to your application. Valid memo block sizes are in the range 8-1024. If anywhere
from 1 to 8 bytes of memo data is stored, a single 8-byte block in the memo file will contain the data. If 9
to 16 bytes of data is stored, two consecutive 8-byte blocks in the memo file will contain the data. Due to
its smaller storage block size, ADM memo files are much more efficient at memo data storage than are
Xbase memo files. The length of the memo data is stored in the memo field in the ADT record. Retrieval
of ADM memo data is more than twice as fast as retrieval of Xbase memo data.

ADM memo files keep a "free block" list in its header. This list indicates which blocks within the file have
been freed. An abandoned block will be reused before adding a new block to the bottom of the ADM file.

Advantage Database Server Service for Windows NT/2000

If the NTFS file system is used the maximum ADM memo file size is 4 terabytes (i.e., 4,398,046,511,104
bytes).

If the FAT32 file system is used the maximum ADM memo file size is 4 gigabytes (i.e., 4,294,967,296
bytes).

18 Advantage File Formats

 Advantage Database Server Guide

Advantage Database Server for Windows 95/98/ME

The maximum ADM memo file size is 4 gigabytes (i.e., 4,294,967,296 bytes).

Advantage Database Server for NetWare

Due to low-level NetWare API limitations the maximum ADM memo file size is 4 gigabytes (i.e.,
4,294,967,296 bytes).

Note The maximum possible memo file size is dependant on the memo block size. The number of blocks
in a memo file can not exceed 4,294,967,296 blocks ( 4 gig ), which means the maximum possible memo
size is dependant on the block size. For example, if the memo block size is left at the default value of 8
bytes, the memo file can grow to a size of ( 8 bytes * 4 gigabytes ) = 34,359,738,368 bytes. However, if
the memo block size is increased to the maximum value of 1024 bytes, the memo file can grow to a size
of (1024 bytes * 4 gigabytes) = 4,398,046,511,104 bytes. ADM Memo Block Usage Example

If the word "Kayak" is stored in an ADM memo file, it will fit in a single 8-byte memo block. If the memo
field information in that record is deleted, the 8-byte block in the memo file is not abandoned. It is added
to the ADM "free list" to be used again. If an additional 600 characters are added to the memo field, the
ADM memo file finds and uses 76 contiguous 8-byte memo blocks in the "free list" to store the new memo
data.

Supported ADT Data Types

The following are the field data types available in ADT tables. Note that the length and format of some
fields are different than their DBF table equivalents. The following data types that are available in DBF
tables are not available in ADT tables: Numeric, ShortDate, General, and Picture.

Type Length Available in Description

DBF Table

Character 1 to 65530 Yes Fixed-length character field that is stored

entirely in the table.

Date 4 Yes 4-byte integer containing a Julian date.

Logical 1 Yes 1-byte logical (boolean) field. Recognized

values for True are '1', 'T', 't', 'Y', and 'y'.

Memo 9 Yes Variable-length memo field containing

character data. Up to 65530 bytes can be
stored in a character memo field. The
memo data is actually stored in a
separate file, called a memo file, to
reduce table bloat.
Double 8 VFP, 8-byte IEEE floating point value in the
Extended range 1.7E +/-308 (15 digits of precision).
The decimal value affects the use of the
field in expressions. It does not affect the
precision of the stored data. If the length
is given, it will be ignored. For example,
"salary, double, 10, 2" and "salary,
double, 2" produce the same field.

Integer 4 VFP, 4-byte long integer values from -

Extended 2,147,483,648 to 2,147,483,647.

Image 9 Extended Variable length memo field containing

Advantage File Formats 19

Advantage Database Server Guide

binary image data. The size of each field

is limited by machine resources. The
binary image data is actually stored in a
separate file, called a memo file, to
reduce table bloat. Updating Image fields
within a transaction is not currently
supported.

Binary 9 Extended Variable length memo field containing

binary data. The size of each field is
limited by machine resources. The binary
data is actually stored in a separate file,
called a memo file, to reduce table bloat.
Updating Binary fields within a
transaction is not currently supported.

ShortInteger 2 No 2-byte short integer value from -32,767

to 32,766.

Time 4 No 4-byte integer representing number of

milliseconds since midnight.

TimeStamp 8 No 8-byte value where the high order 4

bytes are an integer containing a Julian
date, and the low order 4 bytes represent
the number of milliseconds since
midnight.

AutoIncrement 4 No 4-byte read-only positive integer value

from 0 to 4,294,967,296 that is unique
for each record in the table.

Raw 1 to 65530 No Fixed length data-typeless raw data field.

CurDouble 8 No Currency data stored internally as an 8-

byte IEEE floating point value in the
range 1.7E +/-308 (15 digits of
precision). The decimal value affects the
use of the field in expressions. It does
not affect the precision of the stored
data. If the length is given, it will be
ignored. For example, "salary,
CurDouble, 10, 2" and "salary,
CurDouble, 2" produce the same field.

ADI Unique Indexes

An ADI index order created with the "unique" property enforces all records in the table to be referenced
via a unique key. When creating the index order, if a record is found that would cause a non-unique key
to be placed in the index, an error will be generated and the index order will not be created. If a unique
index is successfully created, and a new record is inserted or updated in which the key produced from the
record is not unique, an error will be returned and the record update will not be allowed. At that point, the
record must be modified such that the key produced is unique. If the record change is not desired or
possible, either the update must be canceled or the table and index must be closed.

20 Advantage File Formats

 Advantage Database Server Guide

ADI Conditional Indexes

Conditional indexes are index orders that allow you to view only those data records that meet a pre-
defined condition. Conditional indexes include only those records that satisfy a given filter expression.
The conditional index expression may be any valid expression that evaluates to a logical value.
Conditional index expression text lengths are limited depending on which type of index is being built. The
table below shows the maximum conditional index expression text length for each conditional index type.

Index Conditional Expression Length

ADI 512 bytes*

* For ADI indexes, the total length of the key expression text and conditional expression text combined
must not exceed 512 characters, including an extra byte for each expression as a null terminator.

ADT Deleted Records

If a delete record operation is performed on a record in an ADT table, the record is not physically
removed from the table. The record is, however, logically removed from the table. Deleted records in an
ADT table are not visible to the application. Deleted records cannot be "un-deleted" or "recalled". The
space used by records deleted from the table are marked for record re-use. That is, a subsequent append
or insert operation will use space marked for re-use before using new space at the end of the table for a
new record. Thus, the size of an ADT table will not increase after an append or insert operation if there is
space marked for re-use in the table.

If the Pack operation is performed on a table, space marked as available for record re-use will be
physically removed from the table.

Advantage File Format Specifications

Xbase File Format Specifications

Description Length

Maximum number of index orders per 50

compound index file
Maximum number of index files open per table 15
Maximum file size (table, index file, and memo 4 gigabytes
file)
Maximum number of records 2 billion
Maximum record length 65530 bytes
Maximum field name length 10 characters
Maximum index order name length 10 characters
Characters allowed in field names Characters 'a'-'z' and 'A'-'Z', digits '0'-'9', and
the underscore '_' character
Characters allowed in index order names Characters 'a'-'z' and 'A'-'Z', digits '0'-'9', and
the underscore '_' character
Maximum number of fields per table 2035
Maximum traditional record filter expression 32,767 characters
text length
Maximum Advantage Optimized Filter (AOF) 32,767 characters
expression text length
Maximum number of transactions Limited by memory
Maximum number of connections Limited by memory
Maximum number of files opened Limited by memory
simultaneously

Advantage File Formats 21

Advantage Database Server Guide

Maximum number of locks Limited by memory

Key/For expression text length NTX 256 bytes

IDX (non-compact) 220 bytes
IDX (compact) 512 bytes**
CDX 512 bytes**
Key/For expression evaluated length NTX 256 bytes
IDX (non-compact) 100 bytes
IDX (compact) 240 bytes
CDX 240 bytes

** The total index expression including Key and For expressions must not be longer than 512 bytes

DBF Field Types and Specifications

Standard DBF Table Data Types
The following are standard field data types available in DBF tables. The length indicates the amount of
data stored in the record image. For fields that include memo file storage, see the description for the
amount of data that can be stored.

Type Length Decimals Description

Character 1 to 65534 N/A Fixed-length character field that is stored

entirely in the table.

Numeric 1 to 32 0 to Length-2 Fixed-length (exact ASCII representation)

numeric.

Date 8 N/A 8-byte date field in the form of CCYYMMDD.

Logical 1 N/A 1-byte logical (boolean) field. Recognized

values for True are '1', 'T', 't', 'Y', and 'y'.

Memo 10 or 4 N/A Variable-length memo field containing

character data. Up to 65530 bytes can be
stored in a character memo field. The memo
data is actually stored in a separate file, called
a memo file, to reduce table bloat.

Extended DBF Table Data Types

The following are extended field data types available in DBF tables. The extended data types are non-
standard DBF extensions. Non-Advantage applications that read DBF tables may not be able to open and
read tables that have extended data types. Visual FoxPro will recognize double, integer, general, and
picture fields.

Type Length Decimals Description

Double 8 0-20 8-byte IEEE floating point value in the range

1.7E +/-308 (15 digits of precision). The decimal
value affects NTX indexes and the use of the
field in expressions. It does not affect the
precision of the stored data. If the length is
given, it will be ignored. For example, "salary,
double, 10, 2" and "salary, double, 2" produce

22 Advantage File Formats

 Advantage Database Server Guide

the same field.

Integer 4 N/A 4-byte long integer values from -2,147,483,648

to 2,147,483,647.

ShortDate 3 N/A 3-byte date field. This type supports the same
range of dates as a standard date field.

Image 10 N/A Variable length memo field containing binary

image data. The size of each field is limited by
machine resources. The binary image data is
actually stored in a separate file, called a memo
file, to reduce table bloat. Updating Image fields
within a transaction is not currently supported.

Binary 10 N/A Variable length memo field containing binary

data. The size of each field is limited by
machine resources. The binary data is actually
stored in a separate file, called a memo file, to
reduce table bloat. Updating Binary fields within
a transaction is not currently supported.

General 10 or 4 N/A Binary OLE data. The size of each field is

limited by machine resources.

Picture 10 or 4 N/A Binary image data. The size of each field is

limited by machine resources.

Advantage Proprietary File Format Specifications

Description Length

Maximum number of index orders per 50

compound index file
Maximum number of index files open per table 15
Maximum table size 4 gigabytes (4,294,967,296 bytes)
Maximum table size (NTFS file system) 16 exabytes (18,446,744,073,709,551,616
bytes)
Maximum index file size 4 gigabytes (4,294,967,296 bytes)
Maximum index file size (NTFS file system) 2 terabytes (2,199,023,255,552 bytes)
Maximum memo file size 4 gigabytes (4,294,967,296 bytes)
Maximum memo file size (NTFS file system) 4 terabytes (4,398,046,511,104 bytes)
Maximum number of records 2 billion. When the Advantage Database
Server code limitations are resolved in a future
release, the maximum number of records in an
ADT table will be 9,223,372,036,854,775,807
records (i.e., 2 ^63 records).
Maximum record length 65530 bytes
Maximum field name length 128 characters
Maximum index order name length 128 characters
Characters allowed in field names Any character value except 0 (NULL), ';' (a
semi-colon), or ',' (a comma)
Characters allowed in index order names Any character value except 0 (NULL), ';' (a

Advantage File Formats 23

Advantage Database Server Guide

semi-colon), or ',' (a comma)

Maximum traditional record filter expression 32,767 characters.
text length
Maximum Advantage Optimized Filter (AOF) 32,767 characters
expression text length
Maximum number of transactions Limited by memory
Maximum number of connections Limited by memory
Maximum number of files opened Limited by memory
simultaneously
Maximum number of locks Limited by memory

Key/For expression text length ADI 512 bytes**

Key/For expression evaluated length ADI 240 bytes

** The total index expression including Key and For expressions must not be longer than 512 bytes

The maximum number of fields per table depends on field name lengths, and can be calculated by:
65135 / ( 10 + AverageFieldNameLength ). For example, if the average field name length is:
10 - then the maximum number of fields per table is 3256 fields
20 - then the maximum number of fields per table is 2171 fields
30 - then the maximum number of fields per table is 1628 fields.

ADT Field Types and Specifications

The following are the field data types available in ADT tables. Note that the length and format of some
fields are different than their DBF table equivalents. The following data types available in DBF tables are
not available in ADT tables: Numeric, ShortDate, General, and Picture.

Type Length Available in Description

DBF Table

Character 1 to 65530 Yes Fixed-length character field that is stored

entirely in the table.

Date 4 Yes 4-byte integer containing a Julian date.

Logical 1 Yes 1-byte logical (boolean) field.

Recognized values for True are '1', 'T', 't',
'Y', and 'y'.

Memo 9 Yes Variable-length memo field containing

character data. Up to 65530 bytes can
be stored in a character memo field. The
memo data is actually stored in a
separate file, called a memo file, to
reduce table bloat.

Double 8 VFP, Extended 8-byte IEEE floating point value in the

range 1.7E +/-308 (15 digits of
precision). The decimal value affects the
use of the field in expressions. It does
not affect the precision of the stored
data. If the length is given, it will be

24 Advantage File Formats

 Advantage Database Server Guide

ignored. For example, "salary, double,

10, 2" and "salary, double, 2" produce
the same field.

Integer 4 VFP, Extended 4-byte long integer values from -

2,147,483,648 to 2,147,483,647.

Image 9 Extended Variable length memo field containing

binary image data. The size of each field
is limited by machine resources. The
binary image data is actually stored in a
separate file, called a memo file, to
reduce table bloat. Updating Image fields
within a transaction is not currently
supported.

Binary 9 Extended Variable length memo field containing

binary data. The size of each field is
limited by machine resources. The binary
data is actually stored in a separate file,
called a memo file, to reduce table bloat.
Updating Binary fields within a
transaction is not currently supported.

ShortInteger 2 No 2-byte short integer value from -32,767

to 32,766.

Time 4 No 4-byte integer internally stored as the

number of milliseconds since midnight.

TimeStamp 8 No 8-byte value where the high order 4

bytes are an integer containing a Julian
date, and the low order 4 bytes are
internally stored as the number of
milliseconds since midnight.

AutoIncrement 4 No 4-byte read-only positive integer value

from 0 to 4,294,967,296 unique for each
record in the table.

Raw 1 to 65530 No Fixed-length data-typeless raw data field.

CurDouble 8 No Currency data stored internally as an 8-

byte IEEE floating point value in the
range 1.7E +/-308 (15 digits of
precision). The decimal value affects the
use of the field in expressions. It does
not affect the precision of the stored
data. If the length is given, it will be
ignored. For example, "salary,
CurDouble, 10, 2" and "salary,
CurDouble, 2" produce the same field

Advantage File Formats 25

Advantage Database Server Guide

Choosing a File Format

Xbase File Format

Sharing Data with Non-Advantage Applications

If you have non-Advantage applications that need access to your database, and you cannot convert those
applications to use Advantage, you will likely be limited to using the Xbase file format. If you are using
report generating software and that software does not use a native Advantage client, nor does it have the
ability to access data via an ODBC driver, that report generator will be unable to use the Advantage
proprietary file format. In this scenario, you could either use the Xbase file format or use a different report
generating software that can use Advantage.

Prefer to Use the Record Deletion Status as a Filter

If a delete record operation is performed on a record on an Xbase table, the record is not physically
removed from the table, nor is the record logically removed from the table. The record is instead "marked
for deletion". Optionally, records marked for deletion can still be visible to the application. Records
marked for deletion can also be "undeleted", or "recalled" as it is referred to in Xbase terminology. Thus,
the deletion status of a record is nothing more than a filter.

If an application is written such that records marked for deletion are still visible and/or can be undeleted,
you will either have to use the Xbase file format or use some scheme other than the record deletion
status to indicate whether a record is visible or not. An alternative scheme would be to set a filter on some
other field in the table, possibly a logical field, used to indicate whether the record should be visible to the
application. Then, rather than "deleting" the record to make it not visible, you would change the value in
the designated field so that it no longer passes the filter condition. Another alternative is to create an
Advantage custom index, and add and drop keys from the custom index to indicate whether the record
should be visible. If one of these alternative schemes can be successfully implemented to eliminate the
need for the deletion status of a record as a filter, then the Advantage proprietary file format could be
used by an application rather than the Xbase file format.

Prefer Traditional Xbase Unique Index Behavior

An Xbase index order created with the "unique" property will only include records that are referenced by
unique values. If two records result in the identical key value, then only one of the records will be
referenced by the index. The second is simply never added, and no error is reported. If the record (of the
two with identical key values) referenced by the unique index is modified such that the key value
changes, that index key will be removed from the index, but the other record with the identical key value
will NOT be added to the unique index. Therefore, no key will be referencing the unique record in the
index. Unique Xbase index orders do not guarantee uniqueness of the field(s) in the index order's key
expression.

Unique indexes in the Advantage proprietary file format guarantee uniqueness of the field(s) in the index
order's key expression. If the value(s) in the field(s) in an Advantage Proprietary unique index order
change such that they are no longer unique, the update will fail.

If you do not want to guarantee uniqueness of field(s) in a table, and if the traditional Xbase behavior of
the "unique" property in Xbase indexes is desirable to you, then you may want to use the Xbase file
format.

26 Advantage File Formats

 Advantage Database Server Guide

Advantage Proprietary File Format

Long Field Names and Long Index Names

Field names and index order names in the Xbase file format are limited to 10 characters in length. Field
names and index order names in the Advantage proprietary file format can be up to 128 characters in
length. If you have the need for field names or index order names longer than 10 characters, you will
have to use the Advantage proprietary file format.

More Characters in Field Names and Index Names

Field names and index order names in the Xbase file format may only contain the letters 'a'-'z' and 'A'-'Z',
digits '0'-'9', and the underscore '_' character. Field names and index order names in the Advantage
proprietary file format may contain any character value except 0 (NULL), ';' (a semi-colon), or ',' (a
comma). If you have the need for nearly any character value in field names or index order names, you will
have to use the Advantage proprietary file format.

Additional Field Data Types

Advantage proprietary tables support Short Integer, Time, Time Stamp, Auto Increment, and Raw field
types in addition to several other field types that Xbase tables support. If you have the need for a field
type to store a 2-byte integer in the smallest amount of space possible, the time of day, the date and time
of day in a single field, a read-only field that is guaranteed to be unique, or a user-definable, data-
typeless, fixed-length field, you will have to use the Advantage proprietary file format.

True Unique Indexes for Primary Key Support

An ADI index order created with the "unique" property enforces all records in the table to be referenced
via a unique key. When creating the index order, if a record is found that would cause a non-unique key
to be placed in the index, an error will be generated and the index order will not be created. If a unique
index is successfully created, and a new record is inserted or updated in which the key produced from the
record is not unique, an error will be returned and the record update will not be allowed. At that point, the
record must be modified such that the key produced is unique. If the record change is not desired or
possible, either the update must be canceled or the table and index must be closed.

If you need to guarantee the uniqueness of values in one or more fields in a table, you may want to use
the Advantage proprietary format and Advantage proprietary unique indexes.

Deleted Records are Invisible and Automatically Reused

If a delete record operation is performed on a record in an ADT table, the record is not physically
removed from the table. The record is, however, logically removed from the table. Deleted records in an
ADT table are not visible to the application. Deleted records cannot be "undeleted" or "recalled". The
space used by records deleted from the table are marked for record reuse. That is, a subsequent append
or insert operation will use space marked for reuse before using new space at the end of the table for a
new record. Thus, the size of an ADT table will not increase after an append or insert operation if there is
space marked for reuse in the table.

If you desire the delete record operation to delete records such that they are no longer visible to any
application and you do not want space used by deleted records to bloat the size of your tables (as can
happen with Xbase tables), you may want to use the Advantage proprietary file format.

Advantage File Formats 27

Advantage Database Server Guide

File Size Support Greater Than 4 Gigabytes

The Advantage proprietary file format can support files sizes greater than 4 gigabytes when used on
NTFS file systems. If the files in your database may grow to greater than 4 gigabytes, you will have to use
the Advantage proprietary format.

Data Type Independent Expression Concatenation Operator

Advantage proprietary files support a concatenation operator ';' (a semi-colon) that can be used in index
and filter expressions. This operator allows any data to be concatenated regardless of data type. For
example, if two fields exist that are named DATE_FIELD and CHAR_FIELD, an index can be built with
the key expression "DATE_FIELD; CHAR_FIELD". The equivalent index expression for a DBF table
would be "DTOS( DATE_FIELD ) + CHAR_FIELD", which concatenates the characters that are the result
of the DTOS function call, and the data stored in the character field.

If you prefer to concatenate fields of different data type in index and filter expressions without having to
use functions to convert the fields to the same data type, you will want to use the Advantage proprietary
format and the data type independent concatenation operator.

More Efficient Memo Block Size

Advantage proprietary ADM memo files have a default storage block size of 8 bytes. If anywhere from 1
to 8 bytes of memo data is stored, a single 8-byte block in the memo file will contain the data. If 9 to 16
bytes of data is stored, two consecutive 8-byte blocks in the memo file will contain the data. Due to its
smaller storage block size, ADM memo files are much more efficient at memo data storage than are
Xbase memo files.

For example, if the word "Kayak" is stored in an ADM memo file, it will fit in a single 8-byte memo block.
On the other hand, with an Xbase FPT memo file, it would take 64 bytes and an Xbase DBT memo file
512 bytes to store this 5 character word. If an additional 60 characters are added to the memo field, the
ADM memo file finds and uses 9 contiguous 8-byte memo blocks in the "free list" to store the new memo
data. With an Xbase FPT memo file, it would take 128 bytes and an Xbase DBT memo file 512 bytes to
store this 65 character value.

Due to the Advantage proprietary memo file format's small block size, ADM memo files store memo data
very efficiently. If reducing memo file size bloat is an issue, you may want to use the Advantage
proprietary format.

Better Performance for Certain Operations

The Advantage proprietary file format is optimized for use by Advantage and thus provides better
performance for certain operations versus performing those operations on Xbase files.

Advantage proprietary ADI index files support per index order write locking and updating. Thus, if an ADI
index file contains multiple index orders, then different Advantage applications can obtain a write lock and
make updates to different index orders in the same index file at the same time. This "per index order write
locking and updating" functionality does not exist in Xbase file formats. If you have compound index files
with many index orders, and concurrent updates to the database are occurring, the updates of the index
files will be faster with Advantage proprietary index files than with Xbase index files.

When reading memo field data with Xbase file formats, it requires two operations be sent to the
Advantage Database Server. One to get the length of the memo data from the memo file, and the other to
read that length of memo data from the memo file. With the Advantage proprietary file format, the length
of the memo data is stored in the memo field in an ADT record. Therefore it requires just a single

28 Advantage File Formats

 Advantage Database Server Guide

operation be sent to the Advantage Database Server to read memo data. Retrieval of ADM memo data
should be nearly twice as fast as retrieval of Xbase memo data.

Advantage proprietary ADI index key data is always stored in binary collating order. Internal comparisons
of ADI keys can always be done with a simple left to right comparison, regardless of data type. Xbase
index file key data is not always stored in binary collating order. Conversion of Xbase key data is
sometimes necessary before comparison operations can be performed. When using non-USA collation
with character data index keys, Xbase key data comparison is always adversely affected. Index lookups
and updates will almost always be faster with the Advantage proprietary file format than with Xbase file
formats.

Xbase file formats do not remove deleted records from DBF tables, nor are index keys that reference
those deleted records removed from index orders. If an application is configured to "hide" deleted Xbase
records, those deleted records must be filtered out by the Advantage Database Server even when
traversing the data in indexed order. The Advantage proprietary file format never has index keys
referencing records that have been deleted. Deleted record filtering is never necessary when traversing
data in an indexed order. Thus, record traversal in indexed order will be faster with the Advantage
proprietary file format than with Xbase file formats.

When appending or inserting records into an Xbase table, a new record is always added to the end of the
table. When appending or inserting records into an Advantage proprietary file format table, a record that
has been previously deleted will be reused rather than adding a new record to the end of a table. Since
increasing the size of a file takes time, appends and insertions of records into a table will be faster on
average with Advantage proprietary tables than with Xbase tables.

The Advantage Transaction Processing System (TPS) uses internal lists in memory to keep track of what
data is pre-transaction data, which is only visible to the applications not involved with the transaction, and
what data has been updated within the transaction, which is only visible to the application in the midst of
the transaction. This TPS visibility functionality is slightly faster with Advantage proprietary file format than
Xbase file formats due to extra data stored in the record that indicates to the Advantage Database Server
which user has updated the record during a transaction.

Several field types take less storage space with Advantage proprietary ADT tables than with Xbase DBF
tables. This leads to smaller record sizes with ADTs than with DBFs. Smaller record sizes mean less data
on the network, and thus faster transfer of records across the network when using Advantage proprietary
tables rather than Xbase tables.

More Suited for Future Enhancements

Advantage proprietary ADT tables have information in the table header that will keep the table from being
opened if the data dictionary in which field level constraints for the table are defined is not also open.
Xbase DBF tables have no such information in the table header. Thus, when Advantage has support for a
data dictionary, enforcement of functionality such as field value constraints can be guaranteed in ADT
tables, but not necessarily in DBF tables if that DBF table is opened while the corresponding data
dictionary is not open.

The Advantage proprietary file format has support for unique index orders that can guarantee uniqueness
of a primary key in a table. The ability to enforce uniqueness of a primary key is required for the primary
key - foreign key relationship used in referential integrity. Thus, if Advantage adds support for referential
integrity functionality, it can only be supported with the Advantage proprietary file format.

The Advantage proprietary file format table header has been designed to allow support for field level
encryption at the Advantage level. Although this functionality is not yet supported, it is functionality that
could not be easily implemented in Xbase file formats.

Advantage File Formats 29

Advantage Database Server Guide

The Advantage proprietary file format table header has been designed to support up to 65535 different
field types. Xbase files can support nowhere near this many field types. If there is ever a need to support
many different field types, this will only be possible with the Advantage proprietary file format.

Support for NULL Values

A NULL value means a field value has either never been initialized or has been deleted. ADT tables
support true NULL values for all data types. When the data from a field is deleted, the field value is set to
NULL. Unless a specific default field value has been specified, when a record is inserted/appended into
an ADT table, all fields are initialized with their NULL value.

DBF tables have no concept of a NULL value. DBFs only have the concept of an "empty" value, which is
usually a common value that field normally contain. For example, 0 is the "empty" value for a DBF table,
but 0 is often a legitimate value a numeric field can contain and is thus not suitable to be treated as a true
NULL value.

In order for NULL values to be truly useful, those NULL values must be their own distinct value that is
interpreted by the database engine as a NULL value. Xbase "empty" values do not fall into this category,
and are no substitute for an actual NULL value.

30 Advantage File Formats

 Advantage Database Server Guide

Advantage Client/Server Architecture

Client/Server Overview
"Client" normally refers to workstations and applications that are attached to a network. "Server" is the
central repository of files that are commonly shared by the "client" applications. True client/server
technology involves an intelligent division of processing between the client and the server. Optimizing
your network resources and performance depends on a complete understanding of the relationship of
"clients" to "servers". For example, certain operations are ideally suited to reside on the client; such as the
user interface and most business rules and operations. Operations involving database access are most
appropriately performed on the server where the data files are located. By contrast, in a non-client/server
application, all database operations are executed on the client while the server simply stores the tables
for sharing among others on the network.

The Advantage Database Server optimizes your client/server architecture by increasing multi-user
performance, database stability, and database security while making it easy to install and integrate
Advantage into your existing applications. Performance improvements are achieved primarily by reducing
network traffic, intelligently maintaining database files, and by providing intelligent lock management.

Multi-User Performance
In a multi-user, networked environment, traffic to and from the network is nearly always the bottleneck
that leads to poor multi-user performance. Thus, the key to improving performance is to reduce the
amount of data transferred across the network.

Optimized Data Access

In non-client/server environments, all application and data processing takes place on the individual client
workstations. The file server, where the data files are located, serves only as an unintelligent, shared hard
disk. The server CPU also remains largely unused. When the database needs to be updated, all
necessary table and index data is read from the server, across the network, to the client workstation.
Actual updates occur on the client workstation. The new data is then sent back across the network where
it is written to the file server. When a piece of information needs to be found in the database, a search of
the database is required. Index data must be read from the server, across the network, to the client
workstation where the search of the data takes place. Index data must be continually read over to the
client until the desired data is found or until it is determined the data does not exist in the database. As a
result, non-client/server database applications typically suffer from poor performance. As more users are
added to the system, the larger the database becomes, the amount of data transferred across the
network increases even more, and performance deteriorates even further.

With the Advantage Database Server, network database application performance is increased
dramatically. Advantage uses the client/server architecture to off-load all index traffic associated with
index look-ups and index maintenance. The Advantage Database Server allows a central point of control
for all database operations. No index data is ever transferred across the network to the client workstation.
All database opens, reads, and writes are performed on the server by the Advantage Database Server
where the data exists. Since no index data and no unnecessary table data is ever sent to the client
workstation, network traffic is drastically reduced and performance increases. An additional benefit of
Advantage client/server technology is that the Advantage Database Server performs all data processing
on the file server, therefore the CPU on the file server is fully utilized. Advantage database applications
have both the workstation CPU and the file server CPU working for them.

Advantage Client/Server Architecture 31

Advantage Database Server Guide

Intelligent Lock Management

Another critical, but often overlooked, factor contributing to increased performance with Advantage
client/server technology is data locking that occurs behind the scenes by the database system. Before
index data can be read or updated, an implicit lock is obtained on that index. As an application developer,
you have no control over when or how these implicit locks are obtained. The database system that the
application is using obtains these locks for you.

In non-client/server environments, all internal locking requests are issued from the individual client
workstations. In multi-user systems, there is much contention for index access. The initial attempts to lock
the index files will often fail because another user already has the index locked. Non-client/server
database systems try and retry the locks from the client, which takes more time and leads to poor
performance for that application. In addition, these lock retries generate increased network traffic that will
slow performance for all users on the network. Non-client/server application index locking generally leads
to slow performance for that individual application as well as compounding performance problems for
other applications on the network.

With Advantage client/server technology, the internal index locks occur on the server. The Advantage
Database Server uses an intelligent lock management system with its proprietary locking mode that
eliminates lock retries and requires no network traffic. The Advantage Database Server uses an internal
queuing algorithm that allows for read-through index locking and immediate index write locking. In non-
client/server systems, there is no differentiation between index "read" locks and index "write" locks. There
is only one kind of lock that can be obtained whether reading or updating an index, and thus all index
access is sequentialized. With the Advantage Database Server, index "read" locks exist as well as index
"write" locks. When an index is being read, there is no danger of that reader changing the structure of that
index. Thus, Advantage allows read-through index locking for index "read" locks. This means all users
who desire to read the same index can get concurrent "read" locks on that index and read from the index
all at the same time. As you can imagine, this increases multi-user index "read" performance immensely.

When an index is being updated, it is possible that the structure of the index may change. Therefore,
when a user obtains a "write" lock on an index, no other users can obtain a "read" or "write" lock on the
index. The Advantage queuing process allows for users to "line up" for access to that index. As soon as
the update operation completes and the "write" lock on the index is released, the next user in the queue
will immediately obtain his index lock and can proceed with the index read or write operation. No lock
retries are ever required. "Write" lock requests are simply queued, and the locks are immediately granted
as soon as the prior user has released the lock. This "write" lock queuing and the elimination of lock
retries significantly increases multi-user database application performance.

Database Stability
During traditional non-client/server interaction between a workstation and server, tables and index files
are susceptible to corruption. Workstations can be interrupted or fail because of a reboot, power failure,
or memory problem. It takes several calls between the workstation and the server to complete an update
operation. If during this process the application, workstation, or network fails, the operation is partially
executed, leaving the database in an unknown state. Index file stability and possibly table stability are
compromised. The following diagram shows the interaction between client and server in a non-
client/server environment during an update to a single record in a table that causes two related indexes to
be updated. Note that if the application, workstation, or network fails at any time between the first index
write and the write of the table record, the database will be left in an unstable and corrupt state.

Note Due to space considerations, the example in the diagram below has been overly simplified. In fact,
many more read and write operations than are shown must occur between the workstation and file server
before each index update can be completed. In actuality, there is even a larger window for possible
database corruption in non-client/server environments than shown.

32 Advantage Client/Server Architecture

 Advantage Database Server Guide

Advantage provides database stability ensuring that every database operation is executed completely or
is not executed at all. Entire database update operations are executed on the server. Therefore, if the
application, workstation, or network fails, the database operation will either successfully be transmitted to
the Advantage Database Server or not transmitted at all. The status of the application, workstation, and
network cannot affect the data in your database. By transmitting entire table and index file update
operations in one command from the client to the server, Advantage eliminates corruption errors
introduced by application, workstation, or network failure. If you have a file server failure, database
corruption can still be eliminated if you are using the Advantage Transaction Processing System.

The following diagram shows the interaction between client and server with Advantage client/server
processing during the same update shown above to a single record in a table which causes two related
indexes to be updated. Note that there is no unstable state with Advantage as no database updates will
occur until all required update information has been received by the Advantage Database Server. Once
all update information has been received, those updates will occur on the server by the Advantage
Database Server requiring no network traffic and no workstation involvement.

Advantage Client/Server Architecture 33

Advantage Database Server Guide

Advantage ISAM File Concepts

Indexed Sequential Access Method (ISAM) Overview

Indexed Sequential Access Method (ISAM) is a scheme used to decrease the amount of time necessary
to locate a data record within a large table, given a unique key for the record. ISAM databases generally
provide better performance than SQL-based relational database systems, especially in small to medium
sized network environments. The Advantage Database Server supports two ISAM file formats: Xbase
DBF and a Proprietary table format.

Advantage ISAM File Types

The Advantage Database Server handles three individual file types: tables, index files, and memo files.

Tables
Tables are the "main" file type containing the rows (records) and columns (fields) of data. The records of
data in the table are a fixed length and do not exist in any sorted order. The data stored in columns in
tables are fixed in length. Each record in the table is assigned a unique record number.

Index Files
Index files contain one or more index orders that allow table data to be viewed in a sorted order based on
one or more columns in a single table, or an expression involving one or more columns in a single table.
Index orders do not physically re-order the records in the table. Instead they provide for a very fast and
efficient method of viewing your table data or searching for a particular item of table data. For example, to
view the table data in rows sorted in "last name" order, the application would have to create an index
order on the "last name" column and make it the "active" index order. As many as 15 index files can be
open at one time per table, and certain types of index files can contain many individual index "orders".
Once an index file is created, that index file must be opened every time the table is opened in order for
updates to the table to be reflected in the index order(s) in the index file. If a table is open and is updated,
but an associated index file is not open, that index file is logically corrupt and must be re-built (re-indexed)
for it to contain valid and current information. ADI and CDX index files can be created as auto-open index
files and, therefore, will automatically be opened when the table is opened and cannot be closed until the
table is closed.

Although multiple index files can be opened per table, only one index order can be "active" for the table.
The active index identifies in what sorted order the table will be viewed. If no index files are open, or if
index files are open but no index order has been made the "active" index order, the table will be viewed in
"natural" order, which is simply record number order. If the table is updated, index orders in all open index
files will be updated whether they are the active index order or not. Updates to index orders automatically
occur when a record in the table is updated, inserted, or deleted. No special code is necessary in the
application to update an index order, other than making sure the index file is open when the table is open.

Memo Files
Advantage supports variable length memo, binary, and image data types. The data for memo, binary,
and image fields are not stored in the table file, but are stored in a separate file called a memo file. Memo
files allow the table to remain relatively small even if data for the memo, binary, and image fields is very
large. The table does contain a short, fixed length field for each memo, binary, and image field, but it is
nothing more than a “pointer” to the data in the memo file. Memo fields contain character data while

34 Advantage ISAM File Concepts

 Advantage Database Server Guide

binary and image fields contain BLOB data. If the table contains no memo, binary, or image fields, no
associated memo file will exist.

Movement Operations
There are several basic movement operations available for use on Advantage ISAM files.

Go Top (First)
Go Top will position to the first record in the table if no index files are open, no index order is active, or no
index order was specified in the Go Top operation. If an index order is active or is specified, then Go Top
will position to the first logical record in the index order. For example, if the index order is on "name", a Go
Top will position to the record containing the first "A" name in the table.

Go Bottom (Last)
Go Bottom will position to the last record in the table if no index files are open, no index order is active, or
no index order was specified in the Go Bottom operation. If an index order is active or is specified, then
Go Bottom will position to the last logical record in the index order. For example, if the index order is on
"name", a Go Bottom will position to the record containing the last "Z" in the table.

Seek (FindKey/FindNearest/GotoKey/GotoNearest)
Seek is a fast and efficient way to search for data in the active or specified index order. Seek will position
to the record containing the data if it is found. For example, if the index order is on "name", a Seek for
"Schmidt" will position to the record containing the first "Schmidt" name.

Skip (Next/Previous/Moveby)
Skip will cause a re-positioning to N records from the current record position, where N is the number of
records specified in the Skip operation. If no index files are open, no index order is active, or no index
order was specified in the Skip operation, the movement will occur in "natural" record number order. If an
index order is active or is specified, then Skip will move in the logical index order. For example, if the
index order is on "name", and you are currently positioned on the "Jones" record, a Skip 1 operation will
re-position to the next "Jones" record in the table as determined by the active or specified index order.

Go To (GotoBookmark)
Go To will position to the record in the table with the specified record number. Index orders have no effect
upon the Go To operation.

Locate
An ISAM Locate is a slow and inefficient way to search for data in the table. An ISAM Locate does a
simple sequential search for data. An ISAM Locate will position to the record containing the data if it is
found. Avoid using the ISAM Locate operation if possible. Seek is the preferred method of searching for
data.

Note If you are a Delphi developer, do not confuse an ISAM Locate with a Delphi Locate. A Delphi
Locate determines the best possible way to search for a piece of data and performs the search in that
manner. An ISAM Locate always does a sequential search and is very inefficient and slow. A Delphi
Locate is usually very efficient and fast.

Advantage ISAM File Concepts 35

Advantage Database Server Guide

Table Sharing Modes

Tables can be opened in one of two sharing modes: exclusive or shared. Opening a table in Exclusive
mode gives only one application access to the table. Opening a table in Shared mode gives other
applications on the network access to the table. In order for multiple applications to share common data,
they must all specify that the file is to be opened in Shared mode.

Existing index files and memo files are always opened in the same sharing mode as the associated table.
For example, if a table is opened in Exclusive mode, then an index file opened on that table will also be
opened in Exclusive mode. All newly created tables and index files are automatically created and remain
open in Exclusive mode.

Locking
Record locking allows a record to be updated in a table that is opened for Shared use in a multi-user
environment. Before a record can be updated, it must first be locked. This will prevent any other user from
updating that specific record, but that record can still be read by other users. Other users, at the same
time, can obtain record locks on other records and update them concurrently with that first user's update
of his record. A table lock locks an entire table, which allows the user who holds the table lock to update
any record in the table while preventing all other users from being able to update or insert records in the
table. Other users can still read the record/table while a record/table lock is in place. Keep in mind that
use of table locks may cause multi-user performance degradation as other users wanting to perform
updates and inserts will have to wait for the table lock to be released. Depending on the Advantage Client
Kit being used, record locking must be explicitly specified before updating a record or it may be implicitly
done for you. See your Advantage Client Kit for more information on explicit or implicit record locking for
record updates. Independent of which Advantage Client is being used, if a record is explicitly locked, it
must be explicitly unlocked. The converse is also true. If a record is implicitly locked, it will be implicitly
unlocked for you after the record update is completed or a movement operation is performed.

When a record is inserted or appended, a lock on that record is implicitly obtained for the user. Therefore,
no explicit record locking is ever required when appending or inserting a record into the table.

Index file locking and memo file locking are always implicitly performed for the user. No special
application logic is required to perform index file or memo file locking. Before an index is read, an implicit
index "read" lock is obtained. Before an index is updated, an implicit index "write" lock is obtained. Before
a memo file is updated, an implicit memo lock is obtained.

If a table is opened for Exclusive use, no locking is necessary because no other user can have the table,
index files, or memo file open. If a lock operation is issued when the table is opened for Exclusive use,
the operation is simply ignored.

Data Update Visibility

Visibility of updates to the database occurs on a per record basis. When an application has a lock on a
record, the client workstation will have a copy of that record in memory. Due to the record lock, that copy
of the record in client memory is guaranteed to be the most recent, and the data in that record can only
be changed by the application that maintains the record lock. Updates to one or more individual fields in
that record remain visible to only that client application until the write of the entire record is flushed to the
Advantage Database Server to be written on the server. Once the Advantage Database Server has
written the record, its contents are visible to all users. If a locked record has been updated by the client, a
"write record" operation or any movement operation will flush the write of that entire record to the server.
Therefore, updates are on a per record basis, and not per field within the record.

36 Advantage ISAM File Concepts

 Advantage Database Server Guide

Filters
Filters allow a subset of the table to be viewed. Filters are set by specifying an expression containing one
or more fields in the table that evaluates to a logical value. Records that pass the filter expression
condition are visible to the application. Records that do not pass the filter condition are not visible to the
application.

Relations (Master/Detail Relationships)

Relations provide for a simple foreign key—primary key type relationship in ISAM file structures. Relations
associate a "child" table to a "parent" table through the child's index. When an application performs a
record movement in the parent table, the child's current record is logically positioned. The actual
movement in the child table is performed on demand for efficiency purposes rather than with each parent
movement. The child record position is determined by seeking for a key resulting from evaluating the
expression against the parent table's current record. The child is repositioned after the parent moves, but
it is valid to navigate anywhere in the child table between movements in the parent.

Types of Indexes
Advantage supports several types of index files and index orders.

Single Order Index Files

A single order index file is an index file containing only one index order. Up to 15 index files can be
opened per table.

Multiple Order (Compound) Index Files

A multiple order index file (also referred to as a compound index file) is an index file containing more than
one index order. An individual index order within a multiple order index file is often referred to as a "tag."
Multiple order index files are easier to maintain than single order index files because in a multiple order
index file just the one index file needs to be opened when the table is opened. Whether an index order is
contained in a single order index file or a multiple order index file has no impact on the functionality of the
index order. Up to 50 index orders (tags) can be contained within a multiple order index file. Up to 15
index files can be opened per table.

Auto-Open (Structural) Index Files

An auto-open index file (also referred to as a structural index file) is a multiple order index file that is
automatically opened when the associated table is opened. Therefore, an auto-open index file does not
need to be explicitly opened when the table is opened. In order for a multiple order index file to be an
auto-open index file, it must contain the same base file name as the table and the index file must exist in
the same directory as the table. Only the extensions of the files will be different. Just as auto-open index
files are automatically opened, they are automatically closed when the table is closed, and cannot be
closed while the table is open.

All multiple order index files that do not have the same base file name as the corresponding table are
considered "non-structural" and will not be automatically opened when the table is opened. The
application needs to specifically open the files or logical corruption will occur if any data is updated.

Advantage ISAM File Concepts 37

Advantage Database Server Guide

Conditional Indexes
Conditional indexes are index orders that allow you to view only those data records that meet a pre-
defined condition. Conditional indexes include only those records which satisfy a given filter expression.
The conditional index's filter expression may be any valid expression that evaluates to a logical value.

Conditional indexes are updated like normal indexes, with records added to or deleted from the index
based on the conditional index's filter expression. As the table is updated, only records that match the
conditional index's filter expression are added to the index. If a record changes and no longer matches
the conditional index's filter expression, the record is removed from the index.

Subindexes
Subindexes are index orders that are built based on another index order, which is usually a conditional
index. A subindex includes only the records contained in the "controlling" index upon which it is based.
This allows the creation of temporary views of data.

Subindexes do not inherit any conditions from the controlling index on which the subindex is based. If
reindexed, the subindex becomes a regular index and is not based on the currently active index.

Note When creating a subindex, any index scopes that exist on the controlling index will NOT be obeyed.

Custom Indexes
Custom indexes are index orders that are originally created "empty". That is, when originally created, the
custom index will not reference any records in the table. References to individual records can be added or
dropped as desired via Advantage client APIs. Custom indexes allow the developer to create a custom
view of the table based on keys that have been added to the custom index order.

Unique Indexes
The unique property of index orders is very different depending on the Advantage table type being used.
For information on unique indexes, see ADI Unique Indexes or Xbase Unique Indexes.

Index Scopes (Ranges)

An index scope allows you to view a subset of records in an index. Top and bottom index key limits may
be defined to retrieve only those records contained within the specified index scope range. The range
acts as a temporary view of an index, allowing extremely fast retrieval of only those records meeting the
index scope range value(s). The range values are determined based on the currently active or specified
index.

38 Advantage ISAM File Concepts

 Advantage Database Server Guide

A Top value and Bottom value are assigned to define the value range. The Top and Bottom values may
be the same value. Once the Top and Bottom values are set, only those records within the range are
visible.

Index scopes should be used when the currently active or specified index key expression contains the
value(s) that are to be the limits of the view of the table. If the value(s) of the limits of the view are not
contained in an index key expression, index scopes cannot be used. Instead, record filters or Advantage
Optimized Filters must be used. For example, if the expression to be used to limit the view of the table is
"state >= 'Idaho'", and if the active or selected index key expression is not 'state', then a traditional record
filter or Advantage Optimized Filter must be used rather than an index scope.

Note Index scope boundary checking is performed on the client and traditional record filters and
Advantage Optimized Filters are handled on the server. However, the client versus server issue is not the
relevant performance factor with index scopes versus filters. The way index scope functionality is
implemented makes it a superior method to view a subset of records as compared to a traditional record
filter or an Advantage Optimized Filter.

To understand the differences between index scopes and traditional record filters, a comparison is
provided.

Supported Expressions
Expressions are used in creating indexes and setting filters. The Advantage Database Server supports
field names, literal values, operators, and the functions in the list below. Refer to your Advantage client-
specific documentation for descriptions of these supported functions.

ABS() PAD()
ALLTRIM() PADC()
AT() PADL()
CHR() PADR()
CTOD() RAT()
CTOT() RECNO()
CTOTS() REVERSE()
DATE() RIGHT()
DAY() ROUND()
DELETED() RTRIM()
DESCEND() SPACE()
DTOC() STOD()
DTOS() STOTS()
EMPTY() STR()
I2BIN() STRZERO()
IF,IIF() SUBSTR()
L2BIN() TIME()
LEFT() TRIM()
LEN() TODAY()
LOWER() TRANSFORM()
LOWERW() TRIM()
LTRIM() UPPER()
MAX() UPPERW()
MIN() VAL()
MONTH() YEAR()

Advantage ISAM File Concepts 39

Advantage Database Server Guide

Note The Advantage Expression Engine does not support memo, binary, and image fields. If memo,
binary, or image fields are used in your expressions, the Advantage Expression Engine will be unable to
evaluate the expression.

Index Scope versus Traditional Record Filters Comparison

In this comparison, let the currently active or selected index key expression be "name". For the cases
when an index scope is described, let the top scope value be 'Jones' and the bottom scope value be
'Phillips'. For the cases when a record filter is described, let the filter expression be "name >= 'Jones'
.AND. name <= 'Phillips'." Both the index scope and record filter include the same number of records
within their boundaries. The following is what actually occurs for specific operations.

Go Top
With an index scope set, a Go Top operation causes a Seek for the index key 'Jones' to occur, in a single
operation. A Go Top with an index scope set is very fast.

With a record filter set, a Go Top first goes to the top of the index (the 'Abbot' key, for instance). Then a
series of sequential skips occur in the index until the first 'Jones' key is found. The number of skips
depends on the number of keys in the index between 'Abbot' and 'Jones'. Therefore, many operations
may occur. A Go Top with an index scope is extremely fast relative to a traditional record filter.

Go Bottom
With an index scope set, a Go Bottom causes a Seek for the index key 'Phillipt' (note that it is 'Phillipt'
rather than 'Phillips'). Then a negative Skip is performed to position the user on the last of any 'Phillips'
keys. Therefore, two operations occur. A Go Bottom with an index scope set is very fast.

With a record filter set, a Go Bottom first goes to the bottom of the index (the 'Zimmerman' key, for
instance). Then a series of sequential negative Skips occur in the index until a 'Phillips' key is found. The
number of negative Skips depends on the number of keys in the index between 'Zimmerman' and
'Phillips'. Thus, many operations occur. A Go Bottom with an index scope is extremely fast relative to a
traditional record filter.

Seek
If the key being Seeked is within the index scope or record filter boundaries (the 'Nelson' key, for
instance), then index scope and record filter performance is identical.

If the key being Seeked is before the top index scope or record filter boundary (the 'Brown' key, for
instance), index scopes are much faster than traditional record filters. With index scopes, a Seek to the
top of the scope (the first 'Jones' key) or an immediate repositioning to the end of file will occur,
depending if Softseek is set. With traditional record filters, a series of skips will be performed (from the
'Brown' key to the 'Jones' key) before the Softseek setting is accounted for.

If the key being Seeked is after the bottom index scope or record filter boundary (the 'Smith' key, for
instance), then index scopes are once again faster than traditional record filters. With index scopes, an
immediate repositioning to the end of file will occur. With record filters, a series of skips will be performed
(starting at the 'Smith' key) until the end of file is reached.

Skip
Performance of Skips is similar to Seeks. If the Skip occurs within the index scope or record filter
boundaries, index scope and record filter performance is identical. If the Skip occurs outside of the index
scope or record filter boundaries, index scopes are again much faster than record filters. See the Seek

40 Advantage ISAM File Concepts

 Advantage Database Server Guide

section above for a full explanation of how Skips work like Seeks when outside the index scope or record
filter boundaries.

Go To
Regardless of which record you are positioning to, Go To performance is identical when using index
scopes and record filters because Go To ignores both scopes and filters.

Advantage ISAM File Concepts 41

Advantage Database Server Guide

Advantage Database Server Features

Database Security
Database security is essential for controlling access to the files in your database. If database security is
not present, there is little or no control over who can update data, delete files, and/or possibly corrupt data
in the database. The Advantage Database Server provides two methods of database security for free
connections:

• Checking the user's network access rights before opening files for that user. See Check Rights for
more information.
• Allowing access to the database via an Advantage application only. See Ignore Rights for more
information.

The Advantage Database Server provides User Account database security for database connections.
See the "Flexible User Access Control" section in the Advantage Data Dictionary for more information.

Check Rights
When a non-Advantage application, whether it be a database application or other application, needs to
open or create a file on the file server, the network operating system will verify that the user has sufficient
network access rights to that directory and/or file before allowing that user to open or create the file. If the
user has no network access rights to the directory and/or file, the network operating system will not allow
the application to open or create the file. If the user has limited network access rights to the directory
and/or file, such as read-only access, the network operating system will only allow the application to open
a file for read-only use.

The Advantage Database Server "Check Rights" security method for free connections obeys this same
concept of verifying user network access rights. The Advantage Database Server will verify the user's
network access rights to a directory and/or file before opening or creating the specified file for the user.
The data is "secure" because only those users with sufficient network access rights can open and/or
modify the data files.

Refer to your Advantage client-specific documentation for more information about how to use the
Advantage "Check Rights" security method for free connections in your application.

Ignore Rights
Restricting a user's network access rights to the directory and/or files as described above in the "check
rights" security method often does not provide enough database security for free connections. If a user
has been given the necessary read, write, create, and/or delete rights necessary to read, write, create,
and/or delete data via the your database application, then that user can also read, write, create, and/or
delete data without using you application. Users can maliciously or accidentally corrupt the database by
writing to the database with uncontrolled database editors. Files in the database could also be purposely
or accidentally deleted entirely. What mission critical database applications often need is an additional
level of security that only allows users to access the database via your database application. That way
the database application has full control over what users are reading, writing, creating, and/or deleting
data in the database. Non-client/server applications have no way to enforce this additional security; the
Advantage Database Server does.

42 Advantage Database Server Features

 Advantage Database Server Guide

The Advantage Database Server "Ignore Rights" security method for free connections allows you to
"hide" files in the database from all users who are not accessing data through an Advantage application.
The first step necessary to provide the Advantage "Ignore Rights" method of security is to have the
system administrator remove network access rights from all users who could potentially damage the
database. Once network access rights have been revoked from users to the database directory and/or
files, users cannot maliciously or accidentally corrupt the database by writing to the database, creating
new files, or deleting existing files in the database because they no longer have access to those files. The
second step necessary to provide the Advantage "Ignore Rights" method of security is use the "Ignore
Rights" method of Advantage rights checking in your application when opening and creating files for free
connections. When a file is to be opened or created by the Advantage Database Server, and "Ignore
Rights" security is being used, the Advantage Database Server will NOT verify that the user has sufficient
network access to the directory and/or file and will open or create the file for the application regardless of
the user's network access rights. The Advantage Database Server can do this because it is running on
the server and is running at a "supervisor" level. Using Advantage's "ignore rights" security method allows
your Advantage application to have full control over who can access the database and how the database
can be modified. Only Advantage applications using the "ignore rights" security method may access the
database. Non-Advantage applications will have no access to the database at all.

The "first step" described in the above paragraph, in which the system administrator should remove
network access rights from all users who could potentially damage the database, is very flexible. You
and/or the system administrator can decide if all users and/or groups will have their network access rights
revoked or if just certain users and/or groups will have their rights revoked. You and/or the system
administrator can also decide if all network rights will be revoked, or if just some rights (such as delete
and write rights) will be revoked. For example, if a report writer is being used, but that report writer is not
an Advantage application, that report writer will be unable to function if all rights have been removed from
all users. If a network "REPORTS" group is created and that group is given read-only access to the
database directory and/or files, then users who are members of the "REPORTS" group can run the report
writer utility in read-only mode against the database.

Refer to your Advantage client-specific documentation for more information about how to use the
Advantage "ignore rights" security method in your application.

Note If you are using the Advantage Database Server for Windows NT/2000, and your data files are
located on a drive using NTFS, that PC's "system" group must have full access to the share that contains
the data in order for the Advantage Database Server service to have access to that data. Note that it must
be that PC's system group that has full access, not the domain's system group.

Configured Semaphore Connection File Directory Often Necessary

When an Advantage application either calls an Advantage "connect" API (if available) or opens the first
table, it establishes a connection between the application and the Advantage Database Server. During
the connect, a semaphore connection file is created by the Advantage Database Server if the Use
Semaphore Files configuration setting is set to 1. The semaphore connection file is implicitly opened by
the Advantage application using a generic file open call. That is, the file is not opened through the
Advantage Database Server. The semaphore connection file is used to aid in determining the connection
status between the workstation and the server. The default directory in which this semaphore connection
file is opened is the server directory specified in the "connect" API or where the first table is to be opened.
The directory in which semaphore connection files are opened is configurable via the Advantage
configuration file, ADS.CFG. Since the semaphore connection file is actually opened from the workstation
and not via the Advantage Database Server, the user must have network READ rights in the directory in
which the semaphore connection file exists.

When using the Advantage "Ignore Rights" method of security, user access rights are usually revoked
from the directory where the data exists and, thus, where the semaphore connection file is created and
needs to be opened. Therefore, it usually makes sense to configure a specific semaphore connection file

Advantage Database Server Features 43

Advantage Database Server Guide

directory in the Advantage Configuration file where no important data exists, but where all users have
been given at least network READ access.

The network administrator can further take advantage of this semaphore connection file creation if the
Use Semaphore Files configuration setting is set to 1 to limit which users can connect to the Advantage
Database Server and have access to the database. Each user's network rights to the configured
semaphore connection file directory will determine if a user can connect to the Advantage Database
Server. Those users having network READ rights in the semaphore connection file directory will be able
to connect to the Advantage Database Server. Those users who do not have network READ rights will
not be able to connect to the Advantage Database Server and thus, will not be able to open any data
files.

Note Opening the semaphore connection file does not obey the Advantage "rights checking" setting. A
user must have at least READ access rights to the directory where the semaphore connection files are
created in order to connect to the Advantage Database Server no matter how the "rights checking" setting
is set.

Advantage Locking Modes

Locking records and files is critical to sharing data on a network. Locking operations help enforce
database stability by preventing other users from accessing the data while it is being updated. In non-
client/server environments, lock management operations occur from the client and can be quite slow. The
Advantage Database Server provides data locking from the server which significantly increases
application locking management and performance. The Advantage Database Server provides an
intelligent, high performance Proprietary locking mode and a Compatibility locking mode for sharing data
with non-Advantage applications.

The Advantage locking method used by the Advantage Database Server can be specified per table.
Please see your client-specific Advantage documentation for information on how to specify which
Advantage locking mode should be used to open a given table.

Advantage Proprietary Locking

The Advantage Database Server uses an intelligent lock management system with its proprietary locking
mode that eliminates lock retries and requires no network traffic. The Advantage Database Server uses
an internal queuing algorithm that allows application locks to occur without making network operating
system lock API calls. All locking information is maintained internally in the lock queues.

Advantage Proprietary locking mode also allows for read-through index locking and immediate index write
locking. When an index is being read, there is no danger of that reader changing the structure of that
index. Thus, Advantage allows read-through index locking for index "read" locks. All users who desire to
read the same index can get concurrent "read" locks on that index and read from the index all at the same
time. As you can imagine, this increases multi-user index "read" performance immensely. When an index
is being updated, it is possible that the structure of the index may change. Thus, when a user obtains a
"write" lock on an index, no other users can obtain a "read" or "write" lock on the index. The Advantage
queuing process allows users to "line up" for access to that index. As soon as the user is done updating
the index and releases the "write" lock on the index, the next user in the queue will immediately obtain an
index lock and can proceed with the index read or write operation. No lock retries are ever required.
"Write" lock requests are simply queued, and the locks are immediately granted as soon as the prior user
has released the lock. This "write" lock queuing and elimination of lock retries, increases multi-user
database application performance.

44 Advantage Database Server Features

 Advantage Database Server Guide

Advantage Proprietary locking is only available with the Advantage "remote" server, which is the
Advantage Database Server. Advantage Proprietary locking is not available with the Advantage Local
Server.

When Advantage Proprietary Locking is used, files are first opened in a "deny write" mode to non-
Advantage users. Since the files cannot be opened in a writable mode by non-Advantage users, the
Advantage Database Server can assume the environment is Advantage-only and internally maintain
specific locking information. Any non-Advantage application can open files in a shared, read-only mode
only. Likewise, the Advantage Database Server cannot open files that were opened by some other
application in a writable mode.

Advantage Proprietary Locking with Advantage ADT Files

When Advantage Proprietary Locking is used on Advantage ADT files, index "write" locking can be
performed per tag. Therefore, multiple applications can be updating different tags in the same ADI file at
the same time. This per tag "write" locking is not available with Xbase index files.

Advantage Compatibility Locking With Xbase Files

With Xbase files, the Advantage Compatibility Locking mode is provided to allow data to be shared by
Advantage applications and non-Advantage applications simultaneously. When using Advantage
Compatibility Locking, the Advantage Database Server cannot make full use of the internal queuing
algorithm for lock management used with Advantage Proprietary Locking. Read-through index locking is
not available. Additionally, locks must be made visible to non-Advantage applications by obtaining
network operating system locks. When using Compatibility Locking, files are opened in the mode
specified by the application. That is, if the file is specified to be opened in a shared mode, the file is
opened by the Advantage Database Server in a "deny none" mode. This also allows non-Advantage
applications to open the tables and index files in a read/write mode.

With Xbase files, Advantage Compatibility Locking is available with the Advantage "remote" server, which
is the Advantage Database Server, and with the Advantage Local Server.

Note Advantage Compatibility Locking allows other applications to write to tables and index files. This
decreases the amount of concurrency Advantage can provide and reduces performance. There is a
possibility of index corruption with Advantage Compatibility Locking because tables and index files may
become only partially updated if a workstation goes down that is running a non-Advantage application. It
is recommended that you use Advantage Compatibility Locking only when first converting your
applications to use Advantage that share files with other non-Advantage applications. Once all
applications are converted to use Advantage, use Advantage Proprietary Locking to regain index integrity
and concurrency control, and improve performance.

Advantage Compatibility Locking with Advantage ADT Files

With Advantage ADT files, the Advantage Compatibility Locking mode allows data to be shared by
Advantage Local Server applications simultaneously. Locks in one Advantage Local Server application
are made visible to other Advantage Local Server applications by obtaining network operating system
locks. Files are opened in the mode specified by the application. Therefore, multiple Advantage Local
Server applications can have the same files open at the same time in a read/write mode.

With ADT files, Advantage Compatibility locking is not available with the Advantage "remote" server,
which is the Advantage Database Server. Advantage Compatibility locking is only available with the
Advantage Local Server.

Advantage Database Server Features 45

Advantage Database Server Guide

Single Application Scalability

An application is scalable if only the single application is needed to access data in various environments.
Advantage provides many scalability features and functions that are accessible from different
development platforms.

With Advantage, functions and/or drivers are provided that allow a single application to open files that
exist on the client workstation as well as files that exist on a file server. A single Advantage application
can access data on a Novell NetWare server using the Advantage Database Server for NetWare, a
Windows NT/2000 server using the Advantage Database Server for Windows NT/2000, or a Windows
95/98/ME server using the Advantage Database Server for Windows 95/98/ME. The same single
application can also communicate to the Advantage Database Server via either the IPX protocol or IP
protocol, depending on which is available and supported.

Advantage Data Dictionary

The Advantage Data Dictionary introduces additional features and functionality that compliments the
Advantage Database Server and Advantage Local Server. With the Advantage Data Dictionary, a
database can be clearly defined with its associated tables and indexes. Access to the database tables
can be more securely guarded by the Advantage servers because users and user groups can be defined
in the database and specific rights can be assigned to the users and user groups. The Advantage Data
Dictionary allows the Advantage server to ensure the logical validity of the data in the database through
the use of field level constraints, record level constraint, and referential integrity. The Advantage Data
Dictionary also supports the use of stored procedures. Descriptions of the database, tables, fields,
indexes, and default field values can be stored in the Advantage Data Dictionary to allow developers to
develop and deploy applications more efficiently.

These features can be implemented programmatically using the Advantage Client Engine API. They can
also be implemented interactively using the Advantage Data Architect utility (arc32.exe) included in the
Advantage Product CD. The Advantage Data Architect utility can also be downloaded from the Advantage
Solutions Web site at http://solutions.AdvantageDatabase.com/.

The following are brief overviews of the features supported by the Advantage Data Dictionary.

Referential Integrity
Referential Integrity (RI) is the means by which primary/foreign key relationships are enforced in a
database. By specifying RI rules you can have the database guarantee, for example, that every sales
representative is assigned to a valid office. Through the use of RI constraints, many business rules can
be enforced by the database server, instead of your application. See Referential Integrity for more
information.

Default Field Values

Normally, when a new record is added into an ADT table, the record is filled with NULL values for each
field. With a database table, default field values can be defined for the fields in an ADT table so when a
new record is added into the table, it can be filled with values other than all NULL. An example is to
automatically fill in the date of record creation.

Field Level Constraints

Field level constraints can be used to ensure that the data entered for each individual field in a record is
logically valid. For example, the price of an item for sale must not be negative. The field level constraints
include the minimum/maximum allowed value for the field, whether the field can have NULL value, and
the error message associated with the constraint verification. This functionality is available to ADT tables

46 Advantage Database Server Features

 Advantage Database Server Guide

only. The field level constraints are checked when a record is modified. If any of the fields in the record
fails the constraint, the update will not be posted to the database and the error messaged associated with
the failed constraint can be retrieved.

Record Level Constraints

Record level constraints can be used to ensure that the data entered for related fields in a record is
logically valid before posting the record to the database. For example, the price of an item for sale must
be greater than the cost of the item. The record level constraints include a logical expression that defines
the relationship between the fields in the record and the error message associated with the constraint
verification. This functionality is available to ADT tables only. The record level constraint is checked when
a record is modified. The update to the record is aborted if the record does not meet the constraint.

Flexible User Access Control

The data dictionary provides means to allow the administrator to set up a user account to control the
access to the database tables, views and stored procedures. To effectively guard against unauthorized
access to the database, it is recommended that all database tables are stored in a secured server
directory that is only visible to the system process. With the database tables not visible to the user, the
only way to access the tables will be through the Advantage Database Server and the Advantage Data
Dictionary. The access control mechanism consists of two database properties: login requirement and
access rights verification. By default, the database is created with no login required and no access rights
verification. In this state, a user can connect to the database through the data dictionary with no user
name and no password and have full access to all tables, views and stored procedures. The next level of
access control will be to require the user connecting to the database with a valid combination of user
name and password. Once the user is authenticated, access to all tables, views and stored procedures
are granted. The next higher level will have both database properties set to TRUE. The user is verified
when connecting to the data dictionary and the user access to individual table, view or stored procedure
is also verified to make sure that proper rights has been of granted to the user. The administrator will be
responsible for setting up the individual user's access to the tables, views, or stored procedures. User
groups can be defined in the database to ease the task of setting up users with similar access rights.

More Secure Encryption

Version 6.0 of the Advantage servers and clients support table encryption using an industrial standard
160-bit encryption algorithm. In addition to encrypting the data in the table, if the table is an ADT
database table, the table's field headers are also encrypted. Individual database tables can be either
completely encrypted or not encrypted. All encrypted database tables are encrypted with a single
password that is stored in the database. This password can be set and changed by the data dictionary
administrator before any database table is encrypted. The table encryption password is securely stored in
the data dictionary and it is automatically available to the users who are properly authenticated by the
Advantage server to access the database. In other words, there is no need for the end user or the
application to remember the table encryption password to access the encrypted database tables.

Views
A view is a virtual table that is not physically stored in the database, but appears exactly like a "real" table.
A view can contain data from one or more tables or other views and is used to store often-used queries or
query sets in a database. Views can be updateable views or read-only views. By giving users access
rights to the views but not giving them rights to the base tables, views can also provide a limited means of
security. For example, a view can be defined to only allow the user to see certain columns in a table while
hiding the data in other columns that contain sensitive information.

Stored Procedures
Advantage Extended Procedures are easy to develop and use stored procedures. Like traditional stored
procedures, Advantage Extended Procedures allow you to execute a set of code at the server where the
data resides. This allows you to remove data intensive tasks from the workstations and reduces your

Advantage Database Server Features 47

Advantage Database Server Guide

network traffic to a single send and receive operation. Unlike traditional stored procedures, however,
Advantage Extended Procedures allow developers to write, store, and execute stored procedures on the
server using their preferred application development tool. No database administrator is required to
develop Advantage Extended Procedures.

Supports Non-auto-open Indexes for SQL Statements

Non-auto-open indexes, such as NTX indexes, can be associated with database tables. Once the non-
auto-open indexes have been associated with a table, they are automatically opened during the opening
of the table and are maintained by the Advantage servers to ensure the logical validity of those indexes.
The server will also use the non-auto-open indexes to optimize the execution of SQL queries.

Referential Integrity

Overview
Referential Integrity (RI) is the means by which primary/foreign key relationships are enforced in a
database. By specifying RI rules you can have the database guarantee, for example, that every sales
representative is assigned to a valid office. Through the use of RI constraints, many business rules can
be enforced by the database server, instead of your application.

The terms "primary key" and "foreign key" are used throughout this documentation.

• Primary Key - A unique identifier for a table. A column or column combination with the property that,
at any given time, no two rows of the table contain the same value in that column or column
combination.

• Foreign Key - A foreign key is a column or combination of columns whose values match the primary
key of some other table. A foreign key does not have to be unique; in fact, foreign keys are often in a
many-to-one relationship to a primary key. Foreign key values should be copies of the primary key
values; no value in the foreign key except NULL should ever exist unless the same value exists in the
primary key. A foreign key may be NULL; if any part of a composite foreign key is NULL, the entire
foreign key is NULL.

Referential Integrity rules are stored in an Advantage Data Dictionary.

Example
Lets look at a simple example using two tables: SALES_REPS and OFFICES. The following SQL
statement is syntactically correct, and with the current state of our example database this statement
would execute and add a new sales rep, "Doug Henry", who works in office number 45:

INSERT INTO SALES_REPS (EMPL_NUM, NAME, REP_OFFICE)

VALUES (69, 'Doug Henry', 45)

No validity checking has been enforced, and even if office number 45 does not exist in the OFFICES
table, Doug Henry will still exist in our database.

To remedy this situation, we'll define one RI rule linking the OFFICES.OFFICE field (as the primary key)
to the SALES_REPS.REP_OFFICE field (as the foreign key). With this rule in place, the previous SQL
statement would not execute without returning an error. Before adding Doug to the SALES_REPS table,
the Advantage Database Server will first ensure that all foreign keys in this new row reference existing
primary keys in their parent tables. Because office number 45 does not exist, the INSERT operation will
fail. The application developer does not write any code to enforce this rule. All work is done by the

48 Advantage Database Server Features

 Advantage Database Server Guide

database server, and the developer can simply catch this error, notify the user of the violation, and
request correct data.

Update and Delete Rules

Referential Integrity allows update and delete rules to be specified for each relation you define. These
rules affect the behavior of the Advantage Database Server when updating and deleting existing parent
rows. There are four possible update/delete rules that can be performed:

Delete Rules
• RESTRICT - Prevents deletion of a row from a parent table if children of the row still exist in a child
table. If applied to our example above, this would make it illegal to delete an office if any sales
representatives were still assigned to the office.
• CASCADE - When a parent row is deleted, automatically delete all child rows. If applied to our
example above, deleting an office would automatically delete every sales representative assigned to
the office.
• SET_NULL - When a parent row is deleted, automatically set all foreign key values to NULL. If
applied to our example above, this would make deleting an office set every sales representative's
office assignment to an unknown office.
• SET_DEFAULT - When a parent row is deleted, automatically set all foreign key values to their
default values. See Advantage Data Dictionary for more information on default field values. If applied
to our example above, this rule would assign sales representatives to some default office if their office
were ever removed. The default office is stored within the data dictionary and is the default field value
for the office field.

Update Rules
RESTRICT - Prevents updating a primary key if foreign key values still exist in a child table. If applied to
our example above, this would make it illegal to change an office number if sales representatives were
still assigned to the office.
CASCADE - When a primary key is updated, automatically update all foreign key values. If applied to our
example above, updating an office number would also update the REP_OFFICE field for each sales
representative currently assigned to the office.
SET_NULL - When a primary key is updated, automatically set all foreign key values to NULL. If applied
to our example above, this would make updates to the office number set every sales representative's
office assignment to an unknown office.
SET_DEFAULT - When a primary key is updated, automatically set all foreign key values to their default
values. See Advantage Data Dictionary for more information on default field values. If applied to our
example above, this rule would assign sales representatives to some default office if their office number
was ever updated. The default office is stored within the data dictionary and is the default field value for
the office field.

NULL Values
Advantage primary keys can contain one NULL value. Advantage foreign keys (as long as they are not
defined with the unique index type) can contain multiple NULL values. NULL values in foreign keys are
often a necessity when dealing with updates to a database that utilizes RI constraints to break a
dependency between primary and foreign keys.

Behind The Scenes

If you have defined multiple RI rules in your database (a very likely scenario) it is important to keep in
mind the operations that the server will be performing on your behalf. Tables involved in RI rules are
grouped together into graphs. The server must have all tables in the graph open to enforce the RI rules
that you have placed on the database. For example, if your application is designed to use the example
database described above, and opens the OFFICES table, keep in mind that behind the scenes the
server has also opened the SALES_REPS table, to maintain your RI constraint.

Advantage Database Server Features 49

Advantage Database Server Guide

How to Define RI Rules

There are three different ways to define and modify RI rules; Advantage Data Architect, TAdsDictionary
component in Delphi/C++Builder, and Advantage Client Engine (ACE) API calls.

At design-time, the easiest way to define and view your database dictionary setup is through the
Advantage Data Architect utility. See the Advantage Data Architect Help documentation (ARC.HLP) for
more information.

If you would like run-time access to data dictionary information, and if you are programming through the
Delphi/C++Builder Advantage client kits, reference the TAdsDictionary documentation in the Advantage
Database Engine for Delphi Help documentation (ADE.HLP).

Direct access to the Database Dictionary is also available through the Advantage Client Engine API. See
the Advantage Client Engine Help documentation for more information.

Server Configuration
There is no additional server configuration related to the use of referential integrity, however, depending
on your database design and the number of concurrent users, it may be necessary to increment the
configured number of work areas and locks. The Advantage Database Server will use more work areas
when enforcing referential integrity rules. Also, cascading deletes may often need to acquire a large
number of record locks (depending on the number of records affected by the cascade) before performing
the actual cascade operation. For more information on configuration parameters, reference the
Advantage Database Server Configuration section of the ADS help file.

Recommended Reading
Advantage Data Dictionary documentation

James R. Groff & Paul N. Weinberg Lan Times Guide to SQL. Berkeley, CA: Osborne McGraw-Hill
ISBN: 007882026X

Encryption
The Advantage Database Server supports encryption of table data in DBF tables and encryption of table
and memo data in ADT tables. Support also exists for encryption of ADT database table header
information. Advantage can physically encrypt data in tables to protect that data from unauthorized
viewing. The Advantage encryption scheme uses a case-sensitive password to encode data, requiring a
password to view data in its unencrypted form. Advantage Database Server encryption capabilities
provide an easy way to integrate data security over the network. The data stored in tables (and ADM
memo files) on the server is encrypted as well as the table data (and memo data with ADT tables) passed
over the network. If the Advantage application has the correct password, it will be able to decrypt the data
on the client.

Advantage encryption is supported on two levels: per table and per record. If the entire table is encrypted,
all fields in all records in the table are encrypted. This includes encryption of memo fields with ADT tables.
A table can also have only selected records encrypted, rather than all records.

The Advantage encryption engine incorporates a 160-bit, industry standard encryption algorithm that
ensures data is secure as it goes over the network.

Only table data is encrypted by Advantage when using encryption with DBF tables, and only table data
and memo data with ADT tables. Encryption does not affect the functionality of existing indexes.
However, if the correct password is not supplied to enable encryption and there are encrypted records in

50 Advantage Database Server Features

 Advantage Database Server Guide

the table, filters may not return correct result sets, and any new indexes created may not be valid. Certain
table operations, such as Pack, may also require the correct password if there are encrypted records in
the table.

Each table can be encrypted with just a single password. If a table contains one or more records that
have been encrypted with that single password, and an application opens that table but does not have the
correct password, those encrypted records will be treated as read-only to the application. If an entire table
has been encrypted, an application will be unable to update, append, or insert records into that table
unless it has the correct password that was used to encrypt the records in that table.

See your Advantage client-specific documentation for more information about Advantage encryption
APIs.

DBF Table Specific Encryption

If an entire DBF table is encrypted, part of the table header will also be encrypted such that non-
Advantage DBF applications will not be able to open the table. Those applications will consider the
encrypted table "corrupt" and will return an error when attempting to open the DBF table.

Reduced File Handle Usage

The slowest operation that can be requested of an application is to open a file, especially in a network
environment. Given this fact, writing fast database applications usually requires that once a table is
opened, it remains open. However, complex database applications often require access to many files.
This is a problem because database operating systems have a limited number of files that can be open at
one time. Non-client/server application developers traditionally have had to open and close files as they
are needed, unnecessarily slowing the application down with the opening overhead.

The Advantage Database Server eliminates this problem by providing a single point of access to the
database. The Advantage Database Server opens data files and provides access to users. The need for
local file handles is eliminated. The need for server file handles eliminated because the Advantage
Database Server does not use any file handles to access a table shared among multiple users. For
example, suppose you had an inventory control program with 25 users. If the program uses 16 tables,
with an average of three index files each, it could require up to 64 file handles (i.e., 16 table handles + (3
index file handles X 16 tables) = 64 file handles being used). To keep all the files open, a typical non-
client/server application would need 64 file handles at each workstation and 1600 file handles at the file
server. The same application using the Advantage Database Server would require no file handles per
workstation and only 64 file handles at the file server.

Note Opening tables and index files may be slower with Advantage than with your non-client/server
application. This is due to the additional overhead of resolving names to establish a connection to the
correct server, among other factors. There is currently no direct workaround. Open the files once at the
beginning of your application and leave them open for the duration.

Advantage Optimized Filters

Advantage Optimized Filters (AOFs) provide high performance filter optimization for Advantage
applications. AOFs speed filter processing by using index keys instead of table records. If a specified field
has an index built on it, an AOF uses the index file rather than the table to process the filter. Reducing the
amount of data that must be retrieved from the disk increases performance.

An AOF can be thought of as a query on the table. When an application calls the API to create an AOF,
the AOF expression is sent to the Advantage Database Server to build the filter. The server uses indexes

Advantage Database Server Features 51

Advantage Database Server Guide

that have been opened for the given table to quickly determine which records are in the AOF. The actual
AOF consists of an array of bits where each bit represents a single record. The bit for each record that
passes the filter condition is turned on.

In general, AOFs are created by matching portions of the filter expression with index key expressions. For
example, if the field "last name" is indexed, Advantage can quickly optimize the filter expression "last
name >= 'S' .AND. last name <= 'Sch'". The Advantage Database Server will Seek to the appropriate
location in the index and traverse the index pages and set bits in the AOF for records that pass the filter
condition. When doing this, Advantage does not read the actual records but will read only the necessary
index pages needed to resolve the filter.

AOFs are only optimized for tables opened with CDX, IDX, or ADI index files. The AOF code does not
support the use of NTX indexes. If an AOF is built on a table opened with NTX index files, the AOF will be
non-optimized. Under certain circumstances, it may still be advantageous to use AOFs rather than
traditional record filters for NTX tables. If multiple passes are to be made through the table with the filter
set (e.g., due to a browse), the AOF will generally be faster because all records that do not pass the filter
condition will be removed from the array of bits during the first pass through the data, and they will not be
read during subsequent passes.

When using AOFs with the Advantage Database Server, there will be some increased resource usage on
the server. This is especially true if non-optimized filters are created. For example, if the filter "lastname =
'Smith'" is used and there is no index available on lastname, the filter will not be optimized. Therefore,
every bit will be turned on initially, and the memory allocation will be approximately RecordCount / 8
bytes. The total memory allocation for a 1,000,000 record table will be approximately 125,000 bytes. As a
developer, you should keep this in mind when using AOFs. The allocation is probably "small" for most
server configurations, but if you have a very large number of users forcing allocations like this, the total
may be prohibitive. The memory allocation for the array of bits is performed in non-contiguous blocks on a
demand basis, so if a huge table has only a few records that pass the filter condition, the actual amount of
allocated memory is usually quite small.

Differences between AOFs and Traditional Record Filters

There are two primary differences between AOFs and traditional record filters. The first is the speed.
When using an AOF, it is usually very fast because records that do not pass the filter condition do not
have to be read from the disk. It does take a small amount of extra time, though, to build the AOF initially.

The other difference between AOFs and traditional record filters is the freshness of the data. Traditional
record filters are evaluated each time a record is requested. Therefore, they always provide an up-to-date
view of the data. Once a fully optimized AOF has been built, it contains the bookmarks of the records that
are in the filter. In general, the Advantage Database Server keeps the filter up-to-date whenever changes
are made to the records in the table. There are two cases, though, where the filter can become out of
date with respect to the actual data in the tables. The first is with Advantage Local Server. Any record
change made by an application will cause all AOFs associated with that table within the application to be
updated, but the change will not be propagated to other applications using the same table. The second
case where an AOF could be out of date is with Advantage Database Server when compatibility locking is
used. In that case, it would be possible for a third-party application to make a record update that would
not be detected by Advantage Database Server. Otherwise, however, AOFs and traditional record filters
will be consistent with each other.

Relative speeds between the two types of filters depend on the number of records in a table, the number
of records that pass a filter condition, the optimization level of the filter, and server speed. It is common,
though, for fully optimized AOFs to return data sets 10 to 100 times faster than traditional record filters.
The largest relative speed difference between the two types of filters will be seen when a small
percentage of records pass the filter condition. For example, if a filter condition passes 1% of the records
in a large table, a fully optimized AOF may be 10 times faster than a traditional record filter. With a filter

52 Advantage Database Server Features

 Advantage Database Server Guide

condition that passes 99% of the records in a table, a fully optimized AOF will be only slightly faster than
a traditional record filter.

AOF Optimization
AOFs can be optimized using one of three levels: Full, Partial, or Not Optimized. For example, the filter
expression "lastname = 'Smith' .AND. firstname = 'John'" will be fully optimized if indexes exist on
"lastname" and "firstname". If an index exists on only one of those fields, the filter will be partially
optimized. If no index exists for either field, the filter will not be optimized. The following rules apply when
using logical operators. The columns labeled Optimization Level refer to a simple expression (e.g.,
"lastname = 'Smith'") or multiple simple expressions joined by logical operators (e.g., "lastname = 'Smith'"
.AND. firstname = 'John'").

Optimization Operator Optimization Resulting Optimization

Level Level Level

Full .AND. Full Full

Full .AND. Not Optimized Partial
Full .AND. Partial Partial
Partial .AND. Partial Partial
Partial .AND. Not Optimized Partial
Not Optimized .AND. Not Optimized Not Optimized
Full .OR. Full Full
Full .OR. Not Optimized Not Optimized
Full .OR. Partial Partial
Partial .OR. Partial Partial
Partial .OR. Not Optimized Not Optimized
Not Optimized .OR. Not Optimized Not Optimized
.NOT. Full Full
.NOT. Partial Not Optimized
.NOT. Not Optimized Not Optimized

For example, consider the filter expression:

hiredate > CTOD('1/1/90') .OR. ( hiredate > CTOD('1/1/85') .AND. deptnum = 15)

If field "hiredate" is indexed and field "deptnum" is not, the expression will be partially optimized. Each
simple expression involving field "hiredate" will be fully optimized but the simple expression involving field
"deptnum" will not be optimized. The expression can be viewed as:

Full .OR. (Full .AND. Not Optimized)

This then resolves to:

Full .OR. Partial

The final result is partial optimization.

For a simple expression to be fully optimized, the left operand of the expression must, in general, match
an existing index expression exactly. For example, if the only index on a table is "UPPER(lastname)", the
AOF expression "lastname = 'Smith'" will not be optimized, but "UPPER(lastname)='SMITH'" will be fully
optimized. A few cases exist where the left operand does not have to match exactly. One case is for
concatenated index expressions. The index expression "lastname + firstname" will be used to fully
optimized the filter "lastname = 'Smith'", but it will not be used for the filter "firstname = 'John'". The
following are other cases where an exact match is not needed:

Advantage Database Server Features 53

Advantage Database Server Guide

• If the function YEAR( fldname ) is used in an AOF expression, Advantage will use indexes of the form
"fldname" or "DTOS( fldname )" to optimize the expression. For example, the filter "YEAR( doh
)=1990" will be optimized if either an index of the form "doh" or "DTOS( doh )" exists.
• If the function EMPTY( fldname ) is used as an AOF expression, Advantage will use indexes built on
"fldname" to optimize the expression. For example, the filter "EMPTY( lastname )" will be optimized if
the index "lastname" exists.
• If the function UPPER( fldname ) is used as the index expression, Advantage will fully optimize filter
expressions of the form "fldname = 'VALUE'" when the quoted text is all upper case. The filter
"fldname = 'value'" would not be optimized because 'value' is lower case.

When a filter is partially optimized or not optimized, each bit set in the AOF indicates that the
corresponding record may or may not be in the filter. Each bit that is cleared indicates that the record is
definitely not in the AOF. Therefore, for each bit set for a partial or non-optimized filter, Advantage must
read the actual record and evaluate some portion of the filter expression against the record to determine
whether or not the record passes the AOF condition.

Operators
Advantage Optimized Filters support the following relational operators.

Operator Description
= Equal to
== Strict equality for string
comparison
< Less than
<= Less than or equal to
> Greater than
>= Greater than or equal to
#, !=, <> Not equal to
$ String containment

For the string containment operator ($) to be optimized, it must have the field name on the left side of the
operator just as with the other operators. For example, the filter expression "'x' $ lastname", which will find
all records that have the character 'x' in the field "lastname", will not be optimized. The containment
operator can be used to efficiently find all records that have one of a set of specific characters in a
specific location. For example, if the index "SUBSTR(category, 3, 1)" existed, then the filter expression
"SUBSTR(category, 3, 1) $ 'aAbB'" would be fully optimized and would find all records that have either an
'A', 'a', 'B', or 'b' in the third character of field "category". It can also be used for longer substrings, but it
would generally be more efficient to use several simple expressions joined with the logical .OR. operator.

Performance Tips
The amount of time required to build the Advantage Optimized Filter depends on the number of index
pages that must be read. For example, the filter "lastname = 'Elliot'" would likely be built very quickly
because very few (possibly only one) index pages would need to be read. On the other hand, the filter
"lastname != 'Elliot'" would take longer to build because most of the index pages would need to be read.
By using the logical not operator, a developer can speed up the AOF builds. For example, the filter ".NOT.
(lastname = 'Elliot')" would build faster than "lastname != 'Elliot'" because the server would only read the
index pages containing 'Elliot' and then invert the resulting array of bits. Another example is "lastname >
'C'" versus ".NOT. (lastname <= 'C')". Assuming an even distribution of last names beginning with each
letter, the latter filter will build faster because the server would read fewer index pages.

With Xbase tables, developers can speed up the filtering of records marked for deletion through the use
of indexes built on "DELETED()". If a table has the index "DELETED()" built, then the AOF engine will

54 Advantage Database Server Features

 Advantage Database Server Guide

automatically use that index to optimize the filtering of records marked for deletion. With ADT tables,
deleted records are not visible to the application, so no optimization of deleted records is necessary.

The Advantage Optimized Filter engine does not use custom or Xbase unique indexes for optimization. In
general, it also does not use conditional indexes. When filtering deleted records in Xbase tables,
however, the AOF engine will use conditional indexes with conditions of "!DELETED()".

For an expression to be optimized, the left hand side of the operator must match an index expression. If it
is on the right side of the operator, it will not be optimized. For example, "'Smith' = lastname" will not be
optimized. This should be coded as "lastname = 'Smith'". In addition, the right hand side of the operator
cannot vary by record. For example, the filter "lastname < firstname" will not be optimized because the
right hand side of the operator contains a field value. You can get around this limitation by creating an
index of the form "(lastname < firstname)". A filter of the form "(lastname < firstname) = .T." will then be
fully optimized.

See your Advantage client-specific documentation for more information about Advantage Optimized Filter
APIs.

Read-Ahead Record Caching

Whenever you perform a Skip (Next/Previous) operation after performing any other movement operation
in your application, the next N number of records (rather than just a single record) will be read and
transferred to the client. This allows the next N - 1 subsequent Skip (Previous/Next) operations to be
performed locally. The record skipped (positioned) to will be retrieved from client memory, rather than
having to be read over the network from the server. This should improve Skip (Previous/Next)
performance, especially when performing such operations as populating a grid or browse window.

The default number of records read and cached on the client is the lesser of 10 or the number of records
that can fit in a burst of packets from the Advantage Database Server to the Advantage client. The default
burst of packets can contain 8 Kbytes of data.

Note that any records cached on the client will not reflect changes made by other users to those records
in the table on the server. Advantage client APIs are available to "dump" the cache of records currently in
memory on the client and to refresh the current record.

The maximum number of records that can be cached on the client is the number of records that fit into 64
Kbytes of data. Each record has 4 bytes of overhead, so the following equation yields the maximum read-
ahead record value N:

N = 65535 / ( record size + 4 )

In theory, the ideal value for the number of records to read-ahead would be the number of records that
normally appear in your application's grid or browse window. For example, if your application's grid or
browse window contains 20 records, you should consider changing the read-ahead record value to 20 so
that the entire set of records can be read with one server request. However, if your application is
repeatedly doing a single Skip (Previous/Next) operation, reading ahead 20 records and not using them
may degrade your application's performance. You may want to experiment with the number of records to
read-ahead in your application to find a value that provides best performance.

See your Advantage client-specific documentation for more information about Advantage Read-Ahead
Record Caching APIs.

The following chart shows how many seconds it took to do 10,000 iterations of consecutive Skip (Next)
operations with various read-ahead record caching values. Since an individual Skip (Next) operation

Advantage Database Server Features 55

Advantage Database Server Guide

takes only milliseconds to perform, 10,000 iterations were necessary to produce result times in readable
whole numbers. For example, to do 10 consecutive Skip (Next) operations with a read-ahead record
value of 1 took 187 seconds. To do the same 10 consecutive Skip (Next) operations with a read-ahead
record value of 10 took just 71 seconds. Thus, if your application commonly does 10 consecutive Skip
(Next) operations, setting the read-ahead record value to 10 would increase your application's Skip (Next)
performance by over 250%.

Time (in seconds) to do 10,000 Iterations of Consecutive Next Operations

Number of Records to Read Ahead

1 5 10 15 20 25
24 401 172 142 130 154 104
23 383 166 141 130 154 106
22 370 166 139 129 154 104
21 354 164 138 130 154 105
20 340 141 103 129 94 104
19 323 141 103 129 93 105
18 309 139 107 128 93 104
Number of 17 298 141 112 129 93 104
Consecutive 16 280 142 113 129 93 105
Skip (Next) 15 259 117 112 81 89 104
Operations 14 248 114 110 80 88 104
13 230 112 110 81 88 103
12 216 114 111 81 88 103
11 200 112 111 80 88 103
10 187 86 71 80 87 103
9 169 88 71 79 87 103
8 151 85 71 80 87 103
7 127 87 73 80 91 102
6 113 86 70 80 91 103
5 99 57 73 81 90 102
4 85 59 71 78 90 103
3 75 59 70 78 90 102
2 60 59 69 76 89 102
1 43 59 71 76 88 102

Note Advantage Read-Ahead Record Caching is a feature of client/server architecture, and therefore is
available with the Advantage Database Server but is not available with the Advantage Local Server.

Transaction Processing System

The Advantage Database Server provides the powerful features of a Transaction Processing System
(TPS) for your Advantage database applications. The Advantage TPS allows an application to perform
multiple insert, update, and delete operations to any number of tables with complete confidence that
either all of the insert, update, and delete operations will be successful or that none of the operations will
occur. In other words, Advantage TPS processes multiple insertions, updates, and deletions as though
they were a single operation.

See Advantage Transaction Processing System for a complete description of this Advantage Database
Server feature.

56 Advantage Database Server Features

 Advantage Database Server Guide

Advantage Extended Procedures

What is an Advantage Extended Procedure?

One of the most practical features of the Advantage Database Server (ADS) is that it allows developers to
create applications using their development tool of choice. Advantage Extended Procedures take that
development freedom a step further by allowing developers to write, store, and execute procedures on
the server using their preferred application development tool.

Compared to Traditional Stored Procedures

In order to understand the flexibility and benefits that Advantage Extended Procedures offer, let's take a
look at traditional stored procedures. Some database engines provide functionality for database
administrators to encapsulate a set of database commands that perform logical tasks from the server.
This encapsulated code is called a stored procedure.

Typically, stored procedures are written in the language of the server. They run independent of an
application and generate predefined output when called from an application. By placing the execution
code as close to the data as possible, data-intensive calls and tasks from the client are handled swiftly
and efficiently on the server, without bogging down the network.

However, traditional stored procedures have a few drawbacks:

• They may require the purchase of add-on software or equipment.
• They often must be written and integrated by the Database Administrator (DBA), not the application
developer.
• They often must be written using the server's proprietary scripting language.
• The process of creating them can be tedious and time consuming.

Move to a New Level of Database Development

The Advantage Database Server streamlines the creation and use of stored procedures. Unlike other
products on the market, you can take full advantage of your existing development products and
knowledge to write and execute stored procedures on the fly. There's no downtime needed to familiarize
yourself with a custom add-in or scripting language. Developers write and maintain the stored procedures
themselves. Because our version of stored procedures goes above and beyond what traditional stored
procedures can do, we've named them "Extended Procedures".
And there are no limits to what you can do with Advantage Extended Procedures. But why would you
want to include them in your application development? Here are some of the most compelling reasons:
• You are not limited simply to what the database can do... you can write an Advantage Extended
Procedure to accomplish anything that any programming tool can do.
• They remove data-intensive tasks from the workstations, reducing your network traffic to a single
send and receive operation.
• They centralize the code sets so multiple applications can share them.
• Developers create and maintain the Advantage Extended Procedures without the aid of a Database
Administrator.
• Developers use their development language of choice, shortening ramp-up time and practically
eliminating any learning curve.
• Advantage offers an all-in-one solution that automates the typical Advantage Extended Procedure
tasks of writing a dynamic link library (DLL) and registering it on the server.
• Advantage Extended Procedures pack a lot of punch but leave a small impression on the overall
server and workstation space.

Note Advantage Extended Procedures are supported with the Advantage Database Server for Windows
NT/2000, the Advantage Database Server for Windows 95/98/ME, and the Advantage Local Server.
Advantage Extended Procedures are not supported with the Advantage Database Server for NetWare."

Advantage Database Server Features 57

Advantage Database Server Guide

Creating an Advantage Extended Procedure

This section will provide a high-level overview of creating an Advantage Extended Procedure. Delphi
users will find a step-by-step tutorial under the 'Developing Applications' section in the Advantage
TDataset Descendant for Delphi/C++Builder Help file (ADE.HLP), along with examples installed with the
Advantage TDataSet Descendant product. C programmers will find detailed example applications
included with the installation of the Advantage Client Engine (ACE).

Advantage Extended Procedure templates and sample code are also available from the Advantage
Developer Zone web page, http://solutions.AdvantageDatabase.com. Click on the 'Downloads' link and
then 'Extended Procedures' to find this sample code.

Create an AEP Source File

Advantage Extended Procedures are implemented as Windows DLLs. Create a new DLL project using
the development environment of your choice. Possible development environments include Microsoft
Visual C++, Borland Delphi, Borland C++Builder, CA Visual Objects, and any other environment capable
of generating Windows DLLs.

The default extension of the library generated will be .dll. Modify the project to generate an output library
with an AEP extension. For example, MyFirstProc.aep.

Note For Delphi/C++Builder Users

An AEP template has been provided for you, which makes generating your AEP as simple as creating
a new project. After installing the Advantage TDataSet Descendant, select New from the File menu.
Select the Projects tab, and choose to create a new Advantage Extended Procedure.

Define Startup and Shutdown Functions

AEP modules can implement two special procedures; Startup and Shutdown. These functions are not
required, but it is often necessary to perform initialization and clean-up tasks for each thread that uses
your AEP. The Startup function will be called by Advantage, on a per-connection basis, the first time a
procedure inside of the AEP module is called. The Shutdown function will be called, on a per-connection
basis, as each connection that has used the AEP is closed. This means the Startup function is called
once for each Advantage connection that begins using procedures inside of the AEP module, and the
Shutdown function is also called once for each Advantage connection that has used procedures inside of
the AEP module.

It's important when developing AEP's to keep in mind that they will be run by a multi-threaded server
(Advantage). The Advantage Database Server does not necessarily use the same thread every time it
executes requests for the client, so thread variables are not a suitable solution for providing client-specific
storage in an AEP. All AEP functions are passed the unique identifier, ulConnectionID. This parameter
can be used by the developer to uniquely identify a client connection. Resources allocated on behalf of
the client (connections, open tables, etc) can be tied to this unique connection id, and retrieved at a later
time.

The Startup and Shutdown functions must be implemented using a standard function prototype defined
by Advantage. Below you will find both the Object Pascal and the C prototypes for these functions:

Object Pascal
function Startup( ulConnectionID: UNSIGNED32;
pucUserName: PChar;
pucPassword: PChar )
: UNSIGNED32; stdcall;

function Shutdown( ulConnectionID: UNSIGNED32;

58 Advantage Database Server Features

 Advantage Database Server Guide

pucUserName: PChar;
pucPassword: Pchar )
: UNSIGNED32; stdcall;

C
UNSIGNED32 _declspec( dllexport ) WINAPI Startup
(
UNSIGNED32 ulConnectionID,
UNSIGNED8 *pucUserName,
UNSIGNED8 *pucPassword
)

UNSIGNED32 _declspec( dllexport ) WINAPI Shutdown

(
UNSIGNED32 ulConnectionID,
UNSIGNED8 *pucUserName,
UNSIGNED8 *pucPassword
)

Parameter Description
ulConnectionID A unique identifier that can be used to associate a
user/connection with state-specific variables and
other connection-specific information.

pucUserName Contains the user name of the user who invoked

the procedure.

pucPassword contains the password of the user who invoked

the procedure. This password can be used along
with the user name parameter to connect to the
Advantage server from within the AEP.

Define Your AEP EntryPoint

All Advantage Extended Procedures must be declared using the following prototype:

Object Pascal
function ProcedureName( ulConnectionID: UNSIGNED32;
pusUserName: PChar;
pucPassword: PChar;
pucProcName: PChar;
ulRecNum: UNSIGNED32;
pucTable1: PChar;
pucTable2: PChar )
: UNSIGNED32; stdcall;

C
UNSIGNED32 _declspec( dllexport ) WINAPI ProcedureName
(
UNSIGNED32 ulConnectionID,
UNSIGNED8 *pucUserName,
UNSIGNED8 *pucPassword,
UNSIGNED8 *pucProcName,
UNSIGNED32 ulRecNum,
UNSIGNED8 *pucTable1,
UNSIGNED8 *pucTable2
)

Parameter Description
ulConnectionID A unique identifier that can be used to associate a
user/connection with state-specific variables and

Advantage Database Server Features 59

Advantage Database Server Guide

other connection-specific information.

pucUserName Contains the user name of the user who invoked

the procedure.

pucPassword Contains the password of the user who invoked the

procedure. This password can be used along with
the user name parameter to connect to the
Advantage server from within the AEP.

pucProcName Contains the name of the stored procedure being

executed.

ulRecNum Reserved for use in a future trigger implementation.

pucTable1 Contains the path and filename of a table that

contains the input parameters for the procedure.
Open this table and read the field values to retrieve
input parameters.

pucTable2 Contains the path and filename of a table that

Advantage will read to return output parameters
back to the client. Open this table and set the field
values to return output parameters back to the
client.

Implement Your Procedure Logic

Once you've declared your procedure you're free to implement your business logic in any manor you see
fit. You have the complete functionality of your development environment at your fingertips.

Register Your Procedure with a Data Dictionary

The final step in generating a new AEP is to register the procedure in your Advantage Data Dictionary.
There are several ways to accomplish this task.

The Advantage Data Architect (ARC) provides a graphical interface that can be used to register your
procedures. Reference the Advantage Data Architect Help file (ARC.HLP) for more details.

It is also possible to use SQL commands to register your procedure. Reference the Advantage SQL
Guide (ads_sql.pdf) documentation on CREATE PROCEDURE for more details.

Executing an Advantage Extended Procedure

Advantage Extended Procedures can be executed using SQL by using the EXECUTE PROCEDURE
statement. Reference the Advantage SQL Guide (ads_sql.pdf) documentation on EXECUTE
PROCEDURE for more details.

Note For Delphi/C++Builder Users

Advantage Extended Procedures can be executed via the TAdsStoredProc component when using
the Advantage TDataSet Descendant. The TAdsStoredProc component is on the Advantage tab of
your component palette. This component encapsulates a procedure call, and simplifies parameter
passing through the use of TParam objects. Reference the TAdsStoredProc documentation in the
ade.hlp file for more details.

60 Advantage Database Server Features

 Advantage Database Server Guide

Testing and Debugging an Advantage Extended Procedure

Because Advantage Extended Procedures are Windows DLLs, there are many ways to test them. One of
the simplest methods is to designate a host application that will call the AEP. A host application can be a
simple client application that calls your procedure. You can then assign the test application to be the host
debug application for your debug session. This feature is available in virtually all development
environments with the ability to generate Windows DLLs.

If your development environment does not provide this functionality, or if you would prefer to keep
Advantage out of the picture until your procedure is fully developed, it is also possible to debug your
procedure by calling it directly. You can create two Advantage Database Tables (ADT's), one for input
parameters and one for output parameters. Populate the input parameter table, and then call your AEP
function directly.

Tips and Tricks

Utilize the Features of the Advantage Data Architect (ARC)

The database management features of ARC make it very easy to register and maintain Advantage
Extended Procedures. It is possible to add/remove procedures through SQL statements, but if you'd
prefer a visual approach, open the database in ARC and maintain your procedures this way.

Delphi/C++Builder Users: Utilize the AEP template provided

Select New from the File menu. Select the Projects tab. You will see an AEP template project. Use this
template to accelerate your AEP development.

DOs and DON'Ts of Advantage Extended Procedures

DO
• Open all input and output tables in a shared mode so that data can be shared with other entities.
• Protect global variables with critical sections.
• Export all procedures. In Delphi this means add them to the exports clause; in C this means declare
them as exported entrypoints.
• Use the connection id passed to Startup, Shutdown, and all procedures to uniquely identify a
connection.
• Use the user name and password parameters when logging into a database from within a procedure.
• DELPHI USERS: Set the TAdsConnection.StoredProcedureConnection property to TRUE on all
connections that live inside an AEP data module.
• C USERS: Include the ADS_STORED_PROC_CON option in the ulOptions parameter when making
Advantage connections from within an AEP.
• Include a string output parameter in your procedures, so you can return informational messages
about any exceptions or errors that may occur on the server side.
• Return a non-zero error code from procedures if you'd like the client application to raise an exception.

DO NOT
• Update the output tables from within a transaction without committing the transaction prior to
returning the data.
• Change the .AEP file extension of the Advantage Extended Procedure.
• If writing directly to the ACE API do not call AdsOpenTable or AdsCreateTable and pass a connection
handle of zero. Always pass a connection handle retrieved from a previous call to AdsConnect60.
• If writing a Delphi/C++Builder AEP always use a TAdsConnection component. Do not open tables
without first pointing them to a TAdsConnection component.

Advantage Database Server Features 61

Advantage Database Server Guide

• Use thread local storage (threadvars). A single client can have multiple different Advantage Database
Server threads performing actions on its behalf. You are never guaranteed the thread that performed
work for your last request will also be performing the work for your next request.
• Raise messages boxes or wait for user input from within an AEP. This will hang the Advantage
worker thread, and you will have to restart the Advantage server to reclaim the thread. AEP's are a
server-side process, and should never require user interaction.

62 Advantage Database Server Features

Advantage Database Server Guide

Advantage Transaction Processing System

Advantage Transaction Processing System

The Advantage Database Server provides the powerful features of a Transaction Processing System
(TPS) for your Advantage database applications. The Advantage TPS allows an application to perform
multiple insert, update, and delete operations to any number of tables with complete confidence that
either all of the insert, update, and delete operations will be successful or that none of the operations will
occur. In other words, Advantage TPS processes multiple insertions, updates, and deletions as though
they were a single operation.

In networked environments, tables and their associated index files are susceptible to corruption if a
workstation crashes or a network failure occurs while the tables and index files are being updated.
Building an audit trail to monitor these failures is difficult. Developing a method to recover from incomplete
updates is even more difficult. Advantage TPS eliminates these problems and protects database integrity
by automatically undoing any updates that were performed in the event of workstation or network failure.
This leaves a database exactly as it was before a transaction began. Advantage brings this functionality,
which is not available in non-client/server products, to your network database applications.

If an application is halfway through a series of updates and the decision is made, for whatever reason, to
not continue, the Advantage TPS will abort all updates. Advantage will "undo" the changes that are
marked in your application as a transaction. By "undoing" the changes, your database will be in a state
exactly as it was before the transaction began.

While updates are being made within a transaction, the Advantage TPS hides the updates from other
users until the data is committed. The uncommitted data is visible only to the application performing the
transaction. The other applications view the data as it was before the transaction began. If the transaction
is rolled back, the uncommitted data is never seen by any users other than the one who was performing
the transaction. If the transaction is committed, the updated data becomes visible all at once. This hiding
of uncommitted data is not available in existing non-client/server applications.

Example of a Transaction
To better illustrate a "transaction", consider the following example. A programmer is developing an order
processing module. The module allows users to input a customer order, asking for customer information
and parts to be ordered. The order information is entered by the user on the screen.

For this example, three items are being purchased by one customer. When the order is completed, four
tables and their associated indexes are to be updated. The tables to be updated are: an Order Table, a
Customer Table, a Parts List Table, and an Inventory Table. The order of database changes occur as
follows:

1. The order is inserted into the Order Table.

2. The customer name and address is updated in the Customer Table, if necessary.
3. Each ordered part is inserted into the Parts List Table.
4. Part quantities are adjusted in the Inventory Table.

63 Advantage Transaction Processing System

Advantage Database Server Guide

For this order, a total of eight records are either inserted or updated in these tables. A record is inserted
into the Order Table containing the order information. A Customer Table record is updated with the new
address information. Three parts are being ordered, so three records are inserted into the Parts Table
and three records are updated in the Inventory Table. All of these insertions and updates also cause
updates to the associated index files.

With the Advantage TPS, the insertions and updates in the above scenario are considered one
transaction. The Advantage TPS logs the insertions and updates to a transaction log file. At any time
during the transaction, the insertions and updates can be aborted by issuing a statement to roll back the
transaction. To save all of the information in the transaction, issue a commit transaction statement, and all
the changes to the tables and associated indexes will be written at one time. Without the Advantage TPS,
there is the possibility that only some of these table and index updates are successfully completed. If only
a portion of these updates are successful, the tables and index files are logically corrupt since the data is
not consistent in all locations. By using the Advantage TPS, the programmer can ensure that all inserts
and updates to the tables and indexes are either completely updated or not updated at all.

Advantage TPS Features

Database Stability
The Advantage TPS maintains database stability in the event of workstation or network failure. Should a
workstation or the network fail during a transaction, a transaction that is being committed will finish to
completion, and an uncommitted transaction will automatically be rolled back. If the file server crashes
during a transaction, the Advantage TPS log files are used when the Advantage Database Server is
reloaded to return the database to a known state.

Note Advantage only guarantees updates to be written to the operating system. The operating system
has the responsibility to physically write information to the server's hard disk.

Data Hiding
The Advantage TPS builds robustness into database applications by only allowing visibility of committed
data. While updates are being made within a transaction, the Advantage TPS hides those updates from
other users until that data is committed. The uncommitted data is visible only to the application performing
the transaction. The other applications view the data as it was before the transaction began. If the
transaction is rolled back, the uncommitted data is never seen by any users other than the one who was
performing the transaction. If the transaction is committed, the updated data becomes visible to all users
at one time.

Recovery from System Failures

Automatic recovery of your database to a known state after a system failure is a key feature of the
Advantage TPS. System failures in this context are server failures, such as operating system read or write
errors. How the Advantage TPS handles system failures depends on what phase the transaction was in
when the system failure occurred.

64 Advantage Transaction Processing System

 Advantage Database Server Guide

A transaction can be in one of three phases: the Build Phase, the Commit Phase, or the Rollback Phase.
The Build Phase is active as insert, update, and delete operations are being issued by the application.
These operations are logged to the transaction log file by the Advantage TPS during this phase. The
Commit Phase occurs after the Advantage application issues a commit transaction statement. This
signals the Advantage TPS to begin writing the database updates that are stored in the transaction log file
to the tables and index files. The Rollback Phase occurs after the Advantage application issues a rollback
transaction statement. This signals the Advantage TPS to abort all database updates that are stored in
the transaction log file. The database is left exactly as it was before the transaction began.

If a system failure occurs during the Build Phase, the Advantage TPS aborts only the insert, update, or
delete operation that was in progress. The database is left as it was before the individual operation
occurred and the transaction remains in the Build Phase. An error is returned to the application indicating
that the insert, update, or delete operation failed.

If a system failure occurs during the Commit Phase, the Advantage TPS puts the transaction into the
Rollback Phase. The entire transaction is aborted (rolled back). The database is left as it was before the
transaction began and the transaction is complete. An error is returned to the application indicating the
transaction was rolled back.

If a system failure occurs during the Rollback Phase, a failed transaction results. The tables and index
files associated with the transaction will be left in a temporarily unstable state. An error is returned to the
application indicating the transaction failed. The application needs to recognize this error and attempt a
failed transaction recovery. While the Advantage Database Server is loaded/started, a failed transaction
can be recovered from by calling the applicable Advantage client "failed transaction recovery" or "TPS
cleanup" API. After the failed transaction recovery is completed, the database will be as it was before the
transaction began. See your Advantage client-specific documentation for more information about the
failed transaction recovery APIs.

Note In order for a failed transaction recovery to be successful, no other applications can have the tables
and index files open that are involved with the transaction.

Recovery from Server Crashes

Should a server crash due to a power outage, abend, or other critical errors while one or more
applications are in the midst of a transaction, a failed transaction(s) will result. The tables and index files
associated with the transaction(s) will be left in a temporarily unstable state. The Advantage TPS can
recover from the failed transactions and return the tables and index files to a known state. After bringing
the file server back up, reload/restart the Advantage Database Server. Loading/starting the Advantage
Database Server automatically triggers failed transaction recovery. Any transactions that were in the Build
Phase when the server crashed will be rolled back. Any transactions that were in the Commit Phase will
continue with the commit. Any transactions that were in the Rollback Phase will continue with the rollback.

Always view the Advantage error log, ADS_ERR.DBF, to determine if the Failed Transaction Recovery
was successful. If a Failed Transaction Recovery error is encountered, contact Extended Systems
Technical Support. It is recommended that periodic server backups be a part of any disaster recovery
plan.

Using Transactions in an Application

When to Use Transactions

Before implementing Advantage TPS, you should define what warrants a "transaction" within the confines
of your application. In most applications, a transaction is a request by a user to save the information
entered in a given screen. If the data entry screen only asks for a person's name and address, the
information collected in the screen is probably stored in one record. Though this is technically a
"transaction", you may not necessarily implement this save operation as a transaction using Advantage

Advantage Transaction Processing System 65

Advantage Database Server Guide

TPS. On the other hand, if the data entry screen is a customer order form, there is a good chance that the
data captured in the screen gets saved to a number of records in one or more tables. You would
implement this save operation as a transaction since you want to ensure that either all the updates are
made or that none are made.

In general, users are not aware of how an application saves information. Nevertheless, the strength of the
application and its ability to ensure database stability is based on the programmer's method for saving
information. Defining what makes a transaction in your application is part of the methodology that will give
your application strength and stability. Usually, if insertions and updates involve multiple records in one or
more tables, you should consider handling the insertions and updates as one transaction.

What to Include in a Transaction

A transaction consists of a command to begin the transaction, the steps to complete the transaction (your
insert, update, and delete operations), and a command to end the transaction. Transactions should be
limited in their complexity. In most applications, the only operations that should be included within
transactions are insert, update, and delete operations. All operations that create files, open files, and
receive user input should be excluded. In general, transactions should open/create files first, read/input
the necessary information, begin the transaction, issue the insert and update operations, and finally,
commit the transaction.

What Not to Include in a Transaction

If transactions are too complex and take too much time, overall system performance can become slow. In
most applications, the only operations that should be included within transactions are insert, update, and
delete operations. The following activities should be avoided within a transaction.

Creating Files
Your application should not create files during a transaction. All tables and indexes required for a
transaction should exist before the transaction begins. Creating tables is a time consuming process. As
transactions take longer to complete, multi-user performance will suffer. Long transactions require data
locks to be held for a long period of time which keeps concurrent users from performing transactions on
common data.

File create operations within a transaction cannot be rolled back. If a transaction is rolled back, the
Advantage TPS does not delete, or "uncreate", any files that are created during a transaction.

Opening Files
Your application should not open files during a transaction. All tables and indexes required for a
transaction should be opened before the transaction begins. If an update needs to be made to a table in
order to complete the transaction, and that table is unable to be opened, the corresponding update
cannot be performed. The application will mostly likely need to roll back the transaction. All previous
update and insert operations performed prior to the failed open will be rolled back due to poor transaction
programming. If all tables and indexes are opened before the transactions begin, this needless waste of
the user's time will be avoided.

File open operations within a transaction cannot be rolled back. If a transaction is rolled back, the
Advantage TPS does not close any files that are opened during a transaction.

Data Locking
Depending on the application, record and file locking may best be performed before a transaction begins.
If an update needs to be made to a record in order to complete the transaction, and the lock operation on
that record fails, the corresponding update cannot be performed. The application will mostly likely need to
roll back the transaction. All previous update and insert operations performed prior to the failed data lock
will be rolled back. If all data locks are acquired before the transaction begins, these unnecessary
transaction rollbacks will be avoided. This may be desirable if, for example, an application must obtain a
large number of locks for a transaction or high contention for record locks is expected.

66 Advantage Transaction Processing System

 Advantage Database Server Guide

If the potential for record lock failure is unlikely, then it may make sense to do record locking within the
transaction and simply rollback the transaction if a lock fails. The code to implement this is often simpler;
the potential drawback is that the server load may be increased due to the unnecessary rollbacks.

Excessive Insert and Update Operations

The number of insert and update operations in a given transaction should be as low as possible. The
more insert and update operations that are performed in a transaction, the longer a transaction takes to
complete. This leads to slower multi-user performance. Long transactions require data locks to be held for
a long period of time, which keeps concurrent users from performing transactions on common data.

If a record has an update pending, and a concurrent user issues a read operation on that data,
Advantage scans internal lists to determine if that data is visible to that user. The scan of the internal lists
will indicate that the user should see the original (pre-transaction) data that is associated with that record.
With many insert and update operations contained in a transaction, the internal lists increase in size and
take longer for concurrent users to read the data associated with the transaction.

The Advantage TPS stores insert and update operations that are issued during the Build Phase in
transaction log files. The insert and update operations are actually written to the operating system during
the Commit Phase. The more insert and update operations issued during a transaction, the longer it takes
to commit a transaction. Transaction performance suffers as Commit Phase times increase.

Reading of User Input

Operations that read in user entered data are slow by nature. If these operations are used within a
transaction, it takes longer to complete the transaction. Long transactions require data locks to be held for
a long period of time, which keeps concurrent users from performing transactions on common data.

Illegal Operations
There are a number of operations that are illegal when issued within a transaction. These operations will
generate an error when they are encountered. See your Advantage client-specific documentation for
more information on which operations are not supported within transactions.

Application Termination
If an application terminates, whether normally or abnormally while within a transaction, the transaction is
automatically rolled back. When the rollback is complete, the database is left as it was before the
transaction began. Do not exit from an application while within a transaction.

Use of Deleted Byte

Advantage TPS, as a default, uses the "deleted" byte in a DBF table record to indicate that the record has
an update or insert pending within a transaction. This does not affect the deletion status of the record. If
you would like to keep the "deleted" byte from being temporarily altered, a one byte character field with
the name "AXS_TPS" can be added to any DBF table being used with TPS. The AXS_TPS field would
then be used by the Advantage TPS rather than the "deleted" byte.

Note Use of the "deleted" byte and the optional "AXS_TPS" field only applies to DBF tables. Advantage
proprietary ADT tables do not have the same concept of a "deleted" byte.

Transactions Exist Per Connection

Transactions exist on a per connection basis. A single transaction involving files located on more than
one file server is not supported. However, an application can have separate transactions that involve
tables located on different file servers since the application would have separate connections to each
server.

Advantage Transaction Processing System 67

Advantage Database Server Guide

Advantage CA-Clipper applications can only have one connection per file server. Therefore, transactions
exist per file server for Advantage CA-Clipper applications. Transactions also exist per file server for
Advantage CA-Visual Objects applications. The file server on which a transaction exists is the one with
the active work area when the begin transaction statement is issued. For example, if
SERVER1/VOL1:\FILE1.DBF is opened in the current work area, and a begin transaction statement is
issued, then the transaction exists on SERVER1 and any work areas using files that are located on
SERVER1.

Advantage Windows clients can have more than one connection per file server. Thus, transactions exist
per connection for Advantage Windows applications. The connection on which a transaction exists is the
one that had the specified connection handle in the begin transaction API. See your Advantage client-
specific documentation for more information on the available transaction APIs.

Advantage TPS Limitations

Due to limitations of current client development platforms, network operating systems, and Advantage
table formats, there are a few transaction features not supported with the Advantage TPS. The
Advantage TPS provides the primary transaction processing features available on the market today.
Other DBMS systems may provide additional features that are not supported by the Advantage TPS.

Transaction Spanning Multiple Servers

The Advantage TPS does not support transactions operating on data located on different servers. A
transaction can only commit or rollback updates made to tables and index files residing on a single file
server.

Nested Transactions
A nested transaction is defined as one transaction contained entirely within another transaction. A nested
transaction is identified if back to back begin transaction statements are encountered before a commit
transaction or rollback transaction statement is encountered. The Advantage TPS generates an error if a
nested transaction is discovered. The Advantage TPS also generates an error if a commit transaction or
rollback transaction statement is issued without first issuing a begin transaction statement. The exception
to this rule is separate transactions that exist on different file servers. See Transactions Exist Per
Connection for more information.

Operations Aborted during Rollback

If a transaction rollback occurs, all insert, update, and delete operations are aborted. A transaction
rollback does not close any files opened during the transaction, does not delete any files created during
the transaction, does not undo any "set" operations issued during the transaction, and does not delete
any index tags added during a transaction.

Advantage Applications Only

The Advantage TPS should only be used on data files being accessed by Advantage applications. Do not
share tables and index files that are being updated within transactions with non-Advantage applications.

Transaction Journaling
Transaction journaling is the process of logging and archiving all updates made to the database, even
after a transaction is completed. Transaction journaling is useful in recovering from server disk crashes.
Advantage does not support transaction journaling. The Advantage TPS maintains transaction log files
while transactions are active. Once the transactions are completed, the transaction log files are erased.

68 Advantage Transaction Processing System

 Advantage Database Server Guide

Savepoints
Some systems allow transactions to be rolled back to a specific state within a transaction. The state is
marked by a savepoint. Advantage TPS does not support savepoints within a transaction.

Appended and Inserted Records after Rollback

In order for new index keys to be built for records appended or inserted into a DBF table during a
transaction, the appended/inserted records are actually inserted into the table before the transaction has
been committed. If the transaction is rolled back, the appended records are not removed from a DBF
table since another user may have appended additional records. Therefore, if a transaction is rolled back,
the Advantage TPS clears out all the fields in the appended/inserted records, marks the
appended/inserted records for deletion, and inserts keys into the associated indexes to reference the
deleted, appended/inserted records. A record re-use algorithm can be implemented, if desired, to account
for and reuse these deleted, appended/inserted records. A periodic Pack of the DBF table would
physically removed these deleted, appended/inserted records from the DBF table. Note that this is only
an issue with DBF tables, not ADT tables.

BLOB Updates
Adding or updating BLOB data in a binary or image field while within a transaction is not currently
supported.

Advantage Transaction Processing System 69

 Advantage Database Server Guide

Advantage Database Server Configuration

The Advantage Database Server can be configured in a variety of ways to fine-tune the Advantage
Database Server to more effectively use the server resources and to gain optimal performance. This
section describes the configuration information accessible with the Advantage Database Server. A
configuration file is provided with the Advantage Database Server for NetWare to ease in assigning and
re-using configuration parameters. For the Advantage Database Server for Windows NT/2000 and the
Advantage Database Server for Windows 95/98/ME, configuration information is stored in the Windows
95/98/ME/NT/2000 Registry.

Advantage Database Server Configuration for NetWare

Advantage NLM Configuration File

A configuration file, ADS.CFG, is installed with the Advantage NLM to assist in defining configuration
parameters. The default ADS.CFG file is shown below.

The parameters can be changed by editing the file ADS.CFG with a standard text editor. The
configuration file is used when loading the Advantage NLM. If the Advantage NLM is already loaded, you
must unload then reload the NLM on the file server to use the newly changed settings.

; Advantage Database Server for NetWare configuration file

;
; The Advantage Database Server NLM reads this configuration file when
; the NLM is loaded. Values input after the keyword and equal sign are
; used to configure the NLM. If no value is inserted after a keyword
; and equal sign, the default is used. Command line values will
; override these configuration file values.
;
; Number of Connections (-C)
; Default = User Option purchased; Range = 1 - No upper limit
CONNECTIONS=
;
; Number of Work Areas (-W)
; Default = (25 x CONNECTIONS); Range = 1 - 250 x max connections
WORKAREAS=
;
; Number of Tables (-D)
; Default = 100; Range = 1 - 250 x maximum number of connections
TABLES=100
;
; Number of Index Files (-I)
; Default = 150; Range = 1 - maximum number of connections x
; 250(max work areas/connection) x 15(max indexes/work area)
INDEXES=150
;
; Number of Data Locks (-L)
; Default = (40 x CONNECTIONS); Range = 1 - No upper limit
LOCKS=
;
; Number of Worker Threads (-T)
; Default = 8; Range = 1 - 1024

Advantage Database Server Configuration 70

 Advantage Database Server Guide

THREADS=8
;
; Maximum Size of Error Log (in KBytes)
; Default = 1000 KBytes; Range = 1 Kbyte - No upper limit
ERROR_LOG_MAX=1000
;
; Error Log and Assert Log Path
; Default = root of SYS volume
; The path must be a fully qualified network path, SERVER\VOLUME:\PATH
ERROR_ASSERT_LOGS=
;
; Semaphore Connection File Path
; Default = path of first table opened
; This setting is only used if the USE_SEMAPHORE_FILES value is non-zero.
; The path must be a fully qualified network path, SERVER\VOLUME:\PATH
SEMAPHORE=
;
; Transaction Log Files Path
; Default = root of SYS volume
; The path must be a fully qualified network path, SERVER\VOLUME:\PATH
TPS_LOGS=
;
; IP Port number for the Advantage communication socket. This only
; applies to NetWare 5 and newer
; Default = 0; Range 0 - 65535
; Zero indicates that the next available socket should be used for IP
; communication with Advantage clients
RECEIVE_IP_PORT=0;

; Use semaphore connection files rather than "keep alive" packets to

; sense when a client application has abnormally disconnected.
; Default = 0
; Zero indicates "keep alive" packets should be used. Any other value
; indicates semaphore connection files should be used.
USE_SEMAPHORE_FILES=0
;
; Timeout value for "keep alive" packets. This is the number of
; seconds that must pass before an abnormally disconnected client's
; connection is removed by the Advantage Database Server.
; Default = 240; Range 10 - 65535
CLIENT_TIMEOUT=240
;
; Use NetWare connection names for the Advantage user name in the
; Management API and utilities.
; Default = 0; Range 0 - 1
; A zero indicates that the client computer name should be used for
; the Advantage user name in the Management API and utilities. A
; one indicates the NetWare connection name should be used.
DISPLAY_NW_CONN_NAMES=0

Advantage NLM Command Line Parameters

Command line parameters can also be used to change many Advantage configuration settings. Not all
parameters may be changed on the command line, however. If command line parameters are specified,
they take precedence over configuration file settings.

Advantage Database Server Configuration 71

Advantage Database Server Guide

The following are valid command line parameters:

-C Number of Connections
-D Number of Tables
-F Disable Failed Transaction Recovery
-H Help Screen
-I Number of Index Files
-L Number of Data Locks
-T Number of Worker Threads
-W Number of Work Areas

Changing the Advantage NLM Configuration

To change the Advantage NLM configuration via the command line, you must unload the NLM then
reload it with new configuration parameters.

Example:

LOAD ADS.NLM -C50 -W75 -D100

Advantage Database Server Configuration for Windows NT/2000

Windows 95/98/ME/NT/2000 Registry

The Windows 95/98/ME/NT/2000 Registry serves as a repository for storing program and configuration
information. The Registry is organized in a tree structure and is maintained individually on every Windows
95/98/ME/NT/2000 Server or Workstation. The database-like structure of the Registry provides
information that was usually only available in CONFIG.SYS, AUTOEXEC.BAT, WIN.INI, or SYSTEM.INI
files on a Windows system.

Using the Configuration Utility with the Advantage Database Server for Windows
NT/2000
The Advantage Database Server for Windows NT/2000 stores configuration information in the Windows
NT/2000 registry. The Advantage Database Server configuration key and values are viewable and
editable via the Configuration Utility, which appears as a tab within the Advantage Configuration Utility for
Windows NT/2000. There are three configuration tabs within the Configuration Utility tab in which
configuration parameter information appears: Database Settings, File Locations, and Miscellaneous
Settings. Each tab's configurable settings are described in Advantage Database Server Configuration
Parameters .

Note Changes to any of the configuration values will not affect the Advantage Database Server Service
until you stop and re-start the Advantage Database Server Service.

Startup Parameters for Windows NT/2000

Startup parameters can also be used to change Advantage configuration settings. If startup parameters
are specified, they take precedence over Advantage configuration settings in the Windows NT/2000
Registry. Note that not all Advantage configurable values may be changed via Startup Parameters. With
Windows NT 4.0, startup parameters can be specified in the Startup Parameters box located in the
Service Control Manager. With Windows NT 2000, startup parameters can be specified by clicking the
Properties button in the Service Control Manager, and using the "Start parameters" edit box.

72 Advantage Database Server Configuration

 Advantage Database Server Guide

The following are valid startup parameters:

-C Number of Connections
-D Number of Tables
-F Disable Failed Transaction Cleanup
-I Number of Index Files
-L Number of Data Locks
-T Number of Worker Threads
-W Number of Work Areas

Using Startup Parameters to Change Advantage Database Server Configuration

To change the Advantage Database Server Service configuration using Startup Parameters, you must
stop the Advantage Database Server Service and re-start it with new configuration parameters specified
in the "Startup Parameters" box (with Windows NT 4.0) or "Start parameters" edit box (with Windows
2000) located in the Service Control Manager.

Enter the desired configuration changes into the "Startup Parameters" box (with Windows NT 4.0) or
"Start parameters" edit box (with Windows 2000). For example, if you wish to change the Advantage
Service configuration to 15 connections, 125 work areas and 60 tables, enter the following valid Startup
Parameter sequence in the "Startup Parameters" box or "Startup parameters" edit box:

-c15 -w125 -d60

Advantage Database Server Configuration for Windows 95/98/ME

Windows 95/98/ME/NT/2000 Registry

The Windows 95/98/ME/NT/2000 Registry serves as a repository for storing program and configuration
information. The Registry is organized in a tree structure and is maintained individually on every Windows
95/98/ME/NT/2000 Server or Workstation. The database-like structure of the Registry provides
information that was usually only available in CONFIG.SYS, AUTOEXEC.BAT, WIN.INI, or SYSTEM.INI
files on a Windows system.

Using the Configuration Utility with the Advantage Database Server for Windows
95/98/ME
The Advantage Database Server for Windows 95/98/ME stores configuration information in the Windows
95/98/ME registry. The Advantage Database Server configuration key and values are viewable and
editable via the Configuration Utility, which appears as a tab within the Advantage Database Server for
Windows 95/98/ME GUI. There are three configuration tabs within the Configuration Utility tab in which
configuration parameter information appears: Database Settings, File Locations, and Miscellaneous
Settings. Each tab's configurable settings are described in Advantage Database Server Configuration
Parameters .

Note Changes to any of the configuration values will not affect the Advantage Database Server until you
stop and re-start the Advantage Database Server executable.

Advantage Database Server Configuration 73

Advantage Database Server Guide

Advantage Database Server Configuration Parameters for NetWare,

Windows NT/2000 and Windows 95/98/ME
The Advantage Database Server configuration parameters are used to control CPU and memory usage.
Altering the default settings might affect memory requirements on your file server.

Note The following configuration settings are OPTIONAL. They are provided for optimization and under
many circumstances will not need to be modified.

Number of Connections (-C)

Number of Tables (-D)
Disable Failed Transaction Recovery (-F)
Help Screen (-H)
Number of Index Files (-I)
Number of Data Locks (-L)
Number of Worker Threads (-T)
Number of Work Areas (-W)
Error Log File Size
Error and Assert Log Path
Use Semaphore Files
Client Timeout
Semaphore Connection File Path
Transaction Log Files Path
IP Port
Flush Frequency
Flush Every Update
Use IP
Minimized On Exit
Display NetWare Connection Names
Use Dynamic Cursors
Partial Connection Timeout
Client Timeout

Number of Connections (-C)

Default = User Option purchased. Range = 1 - no upper limit.

This is the maximum number of connections that can be active on the Advantage Database Server at one
time. Connections are defined as follows:
• For Advantage DOS-based applications, a "connection" is defined as a single application connected
to the Advantage Database Server.
• For Advantage 16-bit Windows applications, a "connection" is defined as a single application
connected to the Advantage Database Server. Additional "connections" to the Advantage Database
Server via calls to the Advantage "connect" API can be obtained.
• For Advantage 32-bit Windows applications, a "connection" is defined as a single application
connected to the Advantage Database Server. Additional "connections" to the Advantage Database
Server can be obtained via calls to the Advantage "connect" API, using an Advantage connection
component, or using an Advantage connection object

For example, to minimize memory usage, if you are licensed for 100 users, but have only 75 connections,
you can save a small amount of memory by configuring the number of connections to 75. Or, if you are
licensed for 20 users but have 3 Advantage applications running on each workstation, the number of
connections should be set to at least 60.

74 Advantage Database Server Configuration

 Advantage Database Server Guide

If one or more Advantage applications attempt to connect to the Advantage Database Server than there
are number of connections configured, the Advantage application which is attempting to connect will
receive a 7033 error, Connection Table Full, until a connection becomes available. For example, if the
Advantage Database Server is configured for a maximum of 20 connections, all 20 connections are
currently being taken up by Advantage applications that are connected one or more times to the
Advantage Database Server, and a new or existing Advantage application attempts to connect to the
Advantage Database Server, that connect request will fail with a 7033 error.

Number of Tables (-D)

Default = 100 Tables. Range = 1 - 250 x the maximum number of connections.

This is the maximum number of distinct tables that can be open at one time. This number cannot be
larger than the number of configured work areas. However, due to the sharing of file handles, this number
can be less than the number of work areas.

The "Number of Tables" configuration setting on the Advantage Database Server is a per-server setting.
That is, one table setting must be available per table opened, no matter how many clients have that table
open. For example, if 5 Advantage clients have opened the same 10 tables, there must be at least 10
tables configured on the Advantage Database Server. Thus, the "Number of Tables" configuration setting
differs from the "Number of Work Areas" setting; in that, the "tables" setting is the number of tables
opened "per server" and the "work areas" setting is the number of tables opened "per client".

If an Advantage application attempts to open a table on the Advantage Database Server that has not yet
been opened by any Advantage application, and the configured number of tables have already been
opened, the Advantage application which is attempting to open that table will receive a 7005 error,
Maximum number of tables exceeded, until a table "element" becomes available. For example, if the
Advantage Database Server is configured for a maximum of 50 concurrently open tables, 50 distinct
tables are already currently open with the Advantage Database Server, and a new or existing Advantage
application attempts to open a table that has not yet been opened by the Advantage Database Server,
that table open request will fail with a 7005 error.

Disable Failed Transaction Recovery (-F)

If your application was in the middle of a transaction during a file server crash, your transaction failed and
you need to return your database to a known state. File server crashes prevent the Advantage Database
Server from completing a transaction. As a default, the Advantage Database Server attempts to complete
any failed transaction when the Advantage Database Server is loaded. This parameter is used to disable
automatic completion of failed transactions when the Advantage Database Server is loaded.

This parameter should be used only if you do not want your failed transaction to be completed. This will
leave your database in an unknown state. By using this parameter, existing failed transaction log files will
not be scanned and your database will not be returned to a known state. If you are using transactions in
your applications, it is NOT recommended that you use this parameter.

Use this parameter only to view the data in the unknown state. Once you scan the data, it is
recommended that you reload the Advantage Database Server without this parameter to complete all
failed transactions.

Advantage Database Server Configuration 75

Advantage Database Server Guide

Help Screen (-H)

for NetWare only
If this parameter is specified when loading the Advantage Database Server for NetWare, the valid
command line configuration parameters are displayed on the screen. The Advantage Database Server for
NetWare will not be loaded if this parameter is specified.

Number of Index Files (-I)

Default = 150 index files. Range = 1 to maximum number of connections x 250 (maximum number of
work areas per connection) x 15 (maximum number of indexes per work area).

This parameter directly relates to the maximum number of distinct index files that can be open at any one
time. As with Number of Tables, you can save memory by setting this default to match the actual number
of open index files.

The "Number of Index Files" configuration setting on the Advantage Database Server is a per-server
setting. That is, one index file must be available per index file opened, no matter how many clients have
that index file open. For example, if 128 Advantage clients have opened the same 14 index files, there
must be at least 14 index files configured on the Advantage Database Server. Thus, the "Number of Index
Files" configuration setting is similar to the "Number of Tables" setting; in that, both settings are the
number of files opened "per server" and not the number of files opened "per client".

If an Advantage application attempts to open an index file on the Advantage Database Server that has
not yet been opened by any Advantage application, and the configured number of index files have
already been opened, the Advantage application that is attempting to open that index file will receive a
7006 error, Maximum number of index files exceeded, until an index file "element" becomes available. For
example, if the Advantage Database Server is configured for a maximum of 50 concurrently open index
files, 50 distinct index files are already currently open with the Advantage Database Server, and a new or
existing Advantage application attempts to open an index file that has not yet been opened by the
Advantage Database Server, that index file open request will fail with a 7006 error.

Note This configurable setting is per index FILE. It does not matter if the index file is a single-order index
file, such as an NTX or IDX index, or if it is a multiple-order index file, such as a CDX or ADI index. The
number of orders that exist in a CDX or ADI index file that are opened has no effect on this setting.

Number of Data Locks (-L)

Default = (40 x CONNECTIONS) data locks. Range = 1 - no upper limit.

This is the maximum number of record locks, table locks, implicit header locks, and implicit index locks
that can be in effect at one time. It may not be necessary to change this parameter. For a frame of
reference, check the Advantage Management Utility for the Max Used number. Increase this parameter
only if Data Locks have been rejected.

The "Number of Data Locks" configuration setting on the Advantage Database Server is a "per-client"
setting. That is, one data lock must be available per record, table, header, or index lock requested per
Advantage client. For example, if 10 Advantage clients each have 15 records or files locked at one time,
there must be at least 150 data locks configured on the Advantage Database Server.

If an Advantage application attempts to obtain a record, table, or index lock, and the configured number of
data locks have already been used, the Advantage application which is attempting to get the lock will
receive a 7007 error, Maximum number of locks exceeded, until a lock "element" becomes available. For
example, if the Advantage Database Server is configured for a maximum of 5000 concurrent data locks,

76 Advantage Database Server Configuration

 Advantage Database Server Guide

5000 data locks are already in use by the Advantage Database Server, and a new or existing Advantage
application attempts to lock a record, table, or index, that lock request will fail with a 7007 error. Data
locks take very little memory. Setting this value to a very high number should not require much server
RAM to be used.

Number of Worker Threads (-T)

Default = 8 worker threads. Range = 1 - 1024.

This is the number of Advantage Database Server worker threads used to service client database
requests. Adjusting the number of worker threads controls CPU utilization of the Advantage Database
Server. If the number of requests exceeds the number of threads, the requests are queued until a worker
thread completes its current request. Increasing this parameter may improve Advantage Database Server
throughput and performance, but it may also reduce the performance of other concurrent server
functions. If the file server running the Advantage Database Server is a dedicated database server,
setting the number of worker threads to the maximum will take a bit more memory, but will maximize
Advantage Database Server throughput.

The Advantage Database Server uses multiple worker threads to execute multiple requests concurrently.
If the worker thread count is set to 1, the Advantage Database Server acts as a single-tasking system,
processing each database request sequentially in the order it is received. The default thread count is 8—
meaning up to eight requests can be executed at one time. In this example, a ninth request would be
queued to wait for the first available worker thread.

By limiting the number of worker threads, you can control the maximum server usage by the Advantage
Database Server. If your server is primarily used for shared database access or heavy index building, you
can set the thread count higher and ensure that the Advantage Database Server runs as fast as possible.
If your server is used by other applications and you want to ensure that other tasks are not slowed when
the Advantage Database Server is busy, you can leave the thread count at 8 or set it even lower.

The result of increasing the number of worker threads is environment dependent. If NetWare server
utilization is over 90%, then increasing the number of worker threads will not likely help Advantage
Database Server for NetWare performance. The system administrator may want to experiment with the
number of worker threads in an attempt to balance system throughput versus individual application
performance.

When an index is built by the Advantage Database Server, the operation is performed using one worker
thread and the worker thread is not relinquished until index building is complete. If all worker threads are
being used to build indexes, other processes are held off until one index is completed. If operations are
being held off, increase the worker thread count.

Number of Work Areas (-W)

Default = (25 x CONNECTIONS) work areas. Range = 1 - 250 x the maximum number of connections.

This is the maximum number of work areas that can be in use at one time. This number is the total sum of
all work areas being used by all clients. Each client connection is limited to a maximum of 250 work
areas.

A work area is a logical "container" that consists of a single open table, an optional memo file, and up to
15 index files. The "Number of Work Areas" configuration setting on the Advantage Database Server is a
per-client setting. That is, one work area must be available for each table opened by every client. For
example, if 5 Advantage clients have opened 10 tables, there must be at least 50 work areas configured
on the Advantage Database Server. It does not matter if those 10 tables are the same tables, or if they
are completely different tables.

Advantage Database Server Configuration 77

Advantage Database Server Guide

If an Advantage application attempts to open a table on the Advantage Database Server, and the
configured number of work areas have already been used, the Advantage application which is attempting
to open that table will receive a 7004 error, Maximum number of work areas exceeded, until a work area
"element" becomes available. For example, if the Advantage Database Server is configured for a
maximum of 500 work areas, 500 tables instances (whether the same table or multiple tables) are already
currently open by existing Advantage applications via the Advantage Database Server, and a new or
existing Advantage application attempts to open a table (whether it is a table already open or not), that
table open request will fail with a 7004 error.

Error Log File Size

Default = 1000 Kbytes. Range = 1 - no upper limit.

The error log file size is the maximum file size the error log file, ADS_ERR.DBF, can reach. Once the
maximum file size is attained, the first one third of the records in the error log table are marked for
deletion and packed automatically. New entries are appended to the end of the file.

The error log is a DBF table used to record any errors encountered by the Advantage Database Server
during execution of client applications. The error log file may be viewed using any standard DBF utility.

Error and Assert Log Path

NetWare
Default = Root of SYS volume.

The Advantage Database Server error log, ADS_ERR.DBF, and assert log, ASSERT.LOG, files may be
stored in any directory on the file server. The default path is the root of the SYS volume. You must specify
the path using a fully qualified network path, SERVER\VOLUME:\PATH
Example: ERROR_ASSERT_LOGS = SERVER1\MAIN:\ADSERROR

Windows NT/2000 and Windows 95/98/ME

Default = Root of the C: drive

The Advantage Database Server error log, ADS_ERR.DBF, and assert log, ASSERT.LOG, files may be
stored in any directory on the server. The default path is the root of the C: drive.
Example: C:\ADSERROR

Use Semaphore Files

Default = 0

Zero indicates that the server will use the Client Timeout setting will be used to determine if clients have
aborted connections rather than the Semaphore Connection File Path option. Any non-zero value will
indicate that the Semaphore Connection File Path configuration parameter should be used. See those
sections for more information.

78 Advantage Database Server Configuration

 Advantage Database Server Guide

Client Timeout
Default = 240

Note that this parameter is only used if the configuration parameter, Use Semaphore Files is set to zero.
The default is zero to indicate that the Client Timeout configuration parameter is to be used as opposed to
the Semaphore Connection File Path configuration parameter. See Semaphore Connection File Path for
more information.

When an Advantage application calls either an Advantage "connect" API (if available) or opens the first
table, it establishes a connection between the application and the Advantage Database Server. The
Advantage Database Server needs to ensure that the client application has not aborted its connection to
the server. The connection is aborted when the application is abnormally halted. Examples would include
a PC being rebooted, a PC's network connection being broken, the application having a GPF or when an
application is halted from within a debugger.

The Advantage server determines if a client had died by keeping track of the last communication the
server received from the client. If the server has not received a communication in a given time, then the
client is disconnected. The timeout delay is 240 seconds by default. The Advantage Client Engine will
start a thread that sends "keep alive" packets to the server at given intervals. These packets are only sent
if necessary. If the client has had other communications within the interval, then the "keep alive" packet is
not sent.

Note that this algorithm is generally an improvement over the Semaphore Connection Files algorithm.
The directory specified in the Semaphore Connection Files option must be configured, so that all users
have read access to the directory. This inherently leads to problems.

The Client Timeout algorithm has two drawbacks, however. Both issues affect the developer more so
than end user. The first is that when an application is halted within the debugger, the keep alive packets
are not sent to the server by the second thread, which is also halted. If the application is halted for more
than the configured time, which is 240 seconds or 4 minutes by default, the server will abort that
applications connection. The second problem is that when the developer aborts an application with a
debugger, the connection is left open. The connection will remain open for the configured time.
Semaphore connection files resulted in the files being closed quicker.

Semaphore Connection File Path

Default = Path of first table opened.

Note This parameter is only used if the configuration parameter USE_SEMAPHORE_FILES is set to a
non-zero value. The default is zero to indicate that semaphore connection files are not used at all. See
the configuration option USE_SEMAPHORE_FILES for more information.

When an Advantage application calls either an Advantage "connect" API (if available) or opens the first
table, it establishes a connection between the application and the Advantage Database Server. During
the connect, a semaphore connection file is created by the Advantage Database Server. That file is
implicitly opened by the Advantage application using a generic file open call. That is, the file is not opened
through the Advantage Database Server. The semaphore connection file is used to aid in determining the
connection status between the workstation and the server. The file allows Advantage to properly maintain
connections and abort connections if the client connection is inactive. The default directory in which this
semaphore connection file is opened is the server directory specified in the "connect" API or where the
first table is to be opened. Since the semaphore connection file is actually opened from the workstation
and not via the Advantage Database Server, the user must have network READ rights in the directory in
which the semaphore connection file exists.

Advantage Database Server Configuration 79

Advantage Database Server Guide

The semaphore connection file is a temporary file and will be named _T-#####.TMP, where ##### is a
five digit number.

A non-default semaphore connection file path is necessary when the first table opened is located in a
directory where the user does not have at least network READ privileges. In this case, the semaphore
connection file path should be set to a directory where the user does have at least network READ
privileges. When using the Advantage "ignore rights" method of security, user access rights are usually
revoked from the directory where the data exists and, thus, where the semaphore connection file is
created. Therefore, it usually makes sense to configure a specific semaphore connection file directory
where no important data exists, but where all users have been given network READ access.

A single semaphore connection file path might also be desirable so that all semaphore connection files for
all applications are maintained in a single location.

The network administrator can further take advantage of this semaphore connection file creation to limit
which users can connect to the Advantage Database Server and have access to the database. Each
user's network rights to the configured semaphore connection file directory will determine if a user can
connect to the Advantage Database Server. Those users with network READ rights in the semaphore
connection file directory will be able to connect to the Advantage Database Server. Users who do not
have network READ rights will not be able to connect to the Advantage Database Server and will not be
able to open any data files.

NetWare
This file may be located on any valid network drive. If you specify a path, the path must be a fully qualified
network path, SERVER\VOLUME:\PATH.

Example: SEMAPHORE = SERVER1\MAIN:\ADSSEM

Windows NT/2000 and Windows 95/98/ME

The Semaphore Connection File Path must be specified as a UNC path. This path may consist of any
valid Share on the server.

Example: \\SERVER1\SHARE1\ADSSEM.

Transaction Log Files Path

Transaction log files are created by the Advantage Transaction Processing System to aid in recording all
database operations executed within a transaction. These files allow the Advantage Database Server to
properly track data changes; updates, appends, and other operations which write to the database. Once a
transaction is committed or rolled back, the log files for the transaction are deleted.

The location of the TPS log files is configurable. A non-default transaction file path may be desirable so
that all transaction files are maintained in a single location. All applications with transactions will store
their information in these files. The transaction log files are named as _T-#####.TPS, where ##### if a
four or five digit number.

NetWare
Default = Root of SYS volume.

These files may be located on any valid network drive. If you specify a path, the path must be a fully
qualified network path, SERVER\VOLUME:\PATH.

80 Advantage Database Server Configuration

 Advantage Database Server Guide

Example: TPS_LOGS = SERVER1\MAIN:\ADSTPS

Windows NT/2000 and Windows 95/98/ME

Default = Root of the C: drive

Example: C:\ADSTPS

IP Port
for NetWare 5.x, Windows NT/2000, and Windows 95/98/ME only
Default = next available IP Port.

By default, the Advantage Database Server will use the next IP port available to communicate via the IP
protocol with Advantage clients. If you want the Advantage Database Server to use a specific IP port,
rather than the next available IP port, then edit this setting. The NETSTAT utility with the option "-a" (i.e.,
"netstat -a") can be used to find out what IP ports are currently in use.

Flush Frequency
for Windows 95/98/ME only
Default = 0 milliseconds. Range = 0 milliseconds - no upper limit.

Windows 95, 98 and ME do not always commit (flush) to disk updates made to files opened "locally" by
the computer in a timely manner. This Flush Frequency value determines how often updates made by the
Advantage Database Server on the Windows 95/98/ME "server" are forcibly flushed to disk by an
Advantage Database Server background thread. As this flush time interval decreases, the committing of
file updates occurs more often, which increases data stability (in cases where the server computer
crashes), but decreases Advantage Database Server performance. The default value of zero disables the
forcible flush to disk functionality. Note that flushes of the Advantage Transaction Log File will occur every
time data is added to the file no matter how the Flush Frequency configuration value is set. This will help
to ensure Transaction Log File stability, but will cause updates during a transaction to occur more slowly
than when not in a transaction.

Flush Every Update

for Windows 95/98/ME only
Default = 0 (Off)

Windows 95, 98 and ME do not always commit (flush) to disk updates made to files opened "locally" by
the computer in a timely manner. This Flush Every Update value determines whether every update made
by the Advantage Database Server on the Windows 95/98/ME "server" are immediately and forcibly
flushed to disk. Setting this value to 1 increases data stability (in cases where the server computer
crashes), but drastically decreases Advantage Database Server performance. The default value of zero
disables the immediate forcible flush to disk functionality. Note that flushes of the Advantage Transaction
Log File will occur every time data is added to the file no matter how the Flush Every Update
configuration value is set. This will help to ensure Transaction Log File stability, but will cause updates
during a transaction to occur more slowly than when not in a transaction.

Advantage Database Server Configuration 81

Advantage Database Server Guide

Use IP
for Windows 95/98/ME only
Default = (specified at installation time).

Windows 95, 98, and ME have a Winsock communication defect that does not allow IP and IPX protocol
communication from the same socket. Thus the Advantage Database Server for Windows 95/98/ME is
only able to support one network protocol at a time. If this Use IP value is set to 1, the Advantage
Database Server will use IP for communication between the clients and the server. If this Use IP value is
set to 0, the Advantage Database Server will use IPX for communication between the clients and the
server.

Minimized On Exit
for Windows 95/98/ME only
Default = (set when ADS.EXE is shut down)

If the Advantage Database Server for Windows 95/98/ME is shut down while the Advantage Database
Server for Windows 95/98/ME GUI is minimized, the Minimized On Exit setting will be set to 1. The next
time the Advantage Database Server for Windows 95/98/ME is started, it will be started "minimized" and
will be in the system tray. If the Advantage Database Server for Windows 95/98/ME is shut down while
the Advantage Database Server for Windows 95/98/ME GUI is visible and not minimized, the Minimized
On Exit setting will be set to 0. The next time the Advantage Database Server for Windows 95/98/ME is
started, it will be started in its "normal" visible state (i.e., it will not be started minimized). This setting is
set automatically by the Advantage Database Server for Windows 95/98/ME when it is shut down. If you
wish to set the state the Advantage Database Server for Windows 95/98/ME GUI is in when it is re-
started, you can manually update this configurable value. To manually update this value, update the
MINIMIZED_ON_EXIT key in the Registry at HKEY_LOCAL_MACHINE\SOFTWARE\Extended
Systems\ADS\Configuration. This registry setting can be set for first time use, if so desired. See Modifying
Configuration Parameters During Installation for more information.

Display NetWare Connection Names

for NetWare only
Default = 0; Range 0 - 1

Use NetWare connection names for the Advantage user name in the Management API and utilities. A
zero indicates that the client computer name will be used for the Advantage user name in the
Management API and Utilities. A one indicates that the NetWare connection name will be used for the
Advantage user name in the Management API and Utilities.

Use Dynamic Cursors

Default is to use dynamic cursors.

A dynamic cursor is one that is updated to reflect changes to the underlying table. When dynamic cursors
are turned on, changes made by any user to the underlying table are reflected in all Advantage Optimized
Filters (AOFs) set on that table by other users. If dynamic cursors are turned off, the only changes made
to an Advantage Optimized Filter are changes that are made to the table by the owner of the Advantage
Optimized Filter. Because many optimizations by the SQL engine are performed through Advantage

82 Advantage Database Server Configuration

 Advantage Database Server Guide

Optimized Filters, this setting can affect SQL statements as well. Turning dynamic cursors off may
increase performance when AOFs are set on the table in which records are being modified. See
Differences Between AOFs and Traditional Record Filters for more information.

To turn off dynamic cursors, perform one of the following.

NetWare
Add the following line in the Advantage Database Server configuration file (ADS.CFG).
USE_DYNAMIC_CURSORS=0

Windows NT/2000
Add the following DWORD using the Registry Editor (REGEDIT.EXE) into the registry.
\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Advantage\Configuration\USE_DYNAMI
C_CURSORS=0

Windows 95/98/ME
Add the following DWORD using the Registry Editor (REGEDIT.EXE) into the registry.
\\HKEY_LOCAL_MACHINE\Software\Extended
Systems\ADS\Configuration\USE_DYNAMIC_CURSORS=0

Partial Connection Timeout

Default is 120000 (2 minutes).

Minimum value is 10000 (10 seconds).

This setting tells the server how long (in milliseconds) to wait for a client to fully connect. If the client does
not fully connected within this time, the server will disconnect the partial connection. This setting should
only need to be increased in very rare conditions where a slow network is causing connection failures. In
this case, this setting should be used in conjunction with the Advantage client setting of Max Timeouts
<jump>. The Max Timeouts <jump> setting is the amount of time the client waits for a response from the
Advantage Database Server.

NetWare
Add the following line in the Advantage Database Server configuration file (ADS.CFG).
PARTIAL_CONNECTION_TIMEOUT=120000

Windows NT/2000
Add the following DWORD using the Registry Editor (REGEDIT.EXE) into the registry.
\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Advantage\Configuration\PARTIAL_CO
NNECTION_TIMEOUT=120000

Windows 95/98/ME
Add the following DWORD using the Registry Editor (REGEDIT.EXE) into the registry.
\\HKEY_LOCAL_MACHINE\Software\Extended
Systems\ADS\Configuration\PARTIAL_CONNECTION_TIMEOUT=120000

Advantage Database Server Configuration 83

Advantage Database Server Guide

Advantage Clients
Add the following entry in the ADS.INI file.
[SETTINGS]
// A Default value of 30 (1 minute) is used if this is 0 or not specified
// 40 means 40 X 2 seconds = 80 seconds.
MAX_TIMEOUTS=40

84 Advantage Database Server Configuration

Advantage Database Server Guide

Advantage Management Information

Advantage NLM Screen

for NetWare

Installation Information
When ADS.NLM is loaded, the main Advantage NLM screen is displayed. The following installation
information appears at the top of the main Advantage NLM screen.

Registered To: The name of the company that owns the product. This information is entered when the
Advantage Database Server is installed.

Serial Number: The serial number is unique to your copy of the Advantage Database Server.

User Option: The maximum number of users (client workstations) that can be connected to this version
of the Advantage Database Server.

Revision: The version number of the Advantage Database Server.

NLM Up Time: The time elapsed since the NLM was last loaded (days/hours/minutes/seconds).

Operations Since Loaded: The number of operations performed by the NLM since it was loaded.

Install Date: The date the Advantage Database Server was installed.

Eval Expiration Date: (Displayed for evaluation units only.) The date the Advantage Database Server
evaluation period will expire.

Log Entries: The number of errors or warnings that have been logged to the Advantage error log file
(ADS_ERR.DBF) since the NLM was loaded.

Database Information
The following database information is listed in the table on the main Advantage NLM screen.

Users/Connections: A "user" is defined as a single-client workstation that is connected to the Advantage

Database Server. The number of users is not configurable because the maximum number of users is
determined by the Advantage Database Server User Option purchased. Connections are defined as:
• For Advantage DOS-based applications, a "connection" is defined as a single application connected
to the Advantage Database Server.
• For Advantage 16-bit Windows applications, a "connection" is defined as a single application
connected to the Advantage Database Server. Additional "connections" to the Advantage Database
Server via calls to the Advantage "connect" API can be obtained.
• For Advantage 32-bit Windows applications, a "connection" is defined as a single application's thread
connected to the Advantage Database Server. Additional "connections" to the Advantage Database
Server via calls to the Advantage "connect" API can be obtained.

Each "user" can have multiple active "connections". "Users" is not configurable, whereas "Connections" is
configurable.

85 Advantage Management Information

Advantage Database Server Guide

Work Areas Opened: A work area is a logical "container" that consists of a single open table, an optional
memo file, and up to 15 index files.

Tables Opened: A table is an individual table within your database.

Index Files Opened: An index file is an individual file that can contain one or more index orders.

Data Locks: The data lock is a record lock, a table lock, an index file lock, a memo file lock, or a table
header lock.

The Advantage NLM screen table includes a column for each database item. Definitions of the four
columns are listed below.

Current: The current number of an item in use.

Max Used: The maximum number of resources actually in use at one time since the Advantage
Database Server NLM was loaded.

Note The "Max Used" information is provided to help system administrators fine-tune the configuration of
the Advantage NLM for optimal performance. For example, if after several days of active use, the
maximum number of data locks in use at one time is 50, the system administrator could reconfigure the
Advantage Database Server to allocate 55 data locks.

Configured: Shows the maximum number of an item that the Advantage Database Server has available.

Rejected: Indicates that a configured value has been exceeded. If numbers frequently appear in this
column, it is an indication that the Advantage NLM should be loaded with increased configuration
parameters, or a larger User Option should be purchased.

Advantage NLM Management Utility

for NetWare
The Advantage NLM Management Utility is a tool within the Advantage NLM accessible from the main
Advantage NLM screen on the file server. The utility allows you to view the current Advantage Database
Server status. Communication statistics, configuration parameter settings and memory usage, connected
users, open files, and worker thread information are options which may be viewed.
From the main Advantage NLM screen, select <F1> Management to enter the Advantage NLM
Management Utility.

Select any one of the options to display current Advantage Database Server settings and status.

Communication Statistics
Communication statistics shows the packet and low level network status between the Advantage clients
and the Advantage Database Server. These items are not configurable in the Advantage Database
Server. However, the data is useful in determining the traffic load and other system-related Advantage
Database Server information.

Total Packets Received: This value represents all data packets received from Advantage clients since
the Advantage Database Server was loaded.

86 Advantage Management Information

 Advantage Database Server Guide

Check-Sum Failures: These represent the number of corrupted packets received over the network.
Corrupted packets are ignored by the Advantage Database Server and new packets are resent from the
clients. This is not something to be concerned with unless the "% of Total Packets" is high. It is difficult to
determine what is "high". Reset the value <F10> and view the results. If large numbers of corruptions
occur in a short period of time, another application may be corrupting the packets. Stop the suspected
application and try again.

Receive Packets Out of Sequence: Communication packets, which are assigned sequence numbers,
are sent between the Advantage client and the Advantage Database Server. If a packet is received out a
sequence, this value will be incremented. Packets may be out of sequence due to a packet getting lost on
the network, which may cause it to show up after others were received. If a packet is out of sequence, the
Advantage Database Server ignores it and waits for the resend.

Receive Requests Out of Sequence: The client is requesting a resend of a packet from the Advantage
Database Server but the Advantage Database Server no longer has the packet available. Identify the
client that is generating the resends. Exit the application and restart it. Monitor the results.

Packet Owner Not Logged In: The Advantage Database Server was unable to communicate with a
client properly and therefore, closed the connection. This occurs when a request for an operation, such as
a Seek, is made before the user is properly connected to the Advantage Database Server. Verify that
your application is properly connecting to the Advantage Database Server. This value is incremented
when the Advantage Database Server initiates a disconnect, and the client is still generating disconnect
requests.

NLM Initiated Disconnect: A normal client disconnect consists of two steps initiated by the client: 1) the
semaphore connection file is closed, and 2) a disconnect request is made. If a client PC crashes, is
turned off without first logging off the network, or if the network goes down, a normal disconnect will not
occur. The Advantage Database Server "watch dog" thread identifies that the client is gone and
disconnects the client automatically. This can also occur on a busy network when step 2 above is not
immediately serviced after step 1 occurs.

Removed Partial Connection: When a client connects to the Advantage Database Server, a reply is
sent to the client. The Advantage Database Server waits for a response from the client to acknowledge
that the reply has been received. If the client does not send a response, the Advantage Database Server
terminates the connection. This is a symptom of an extremely busy network.

Advantage Database Server Configuration Parameters

When loading the Advantage Database Server, several parameters may be configured to more closely
match your system requirements. Many of these parameters affect how much server memory is used by
the Advantage Database Server when it is initially loaded. The remaining configurable parameters affect
other non-memory Advantage settings.

If memory usage is a concern, please view the parameter settings that affect how much server memory is
used by the Advantage Database Server. Adjust your configuration parameters accordingly. To change
these parameters, see Advantage Database Server Configuration for more information.

Configuration Parameters Affecting Memory: To view the currently loaded parameters affecting
memory when the Advantage Database Server is loaded, select "Configuration Parameters" from the
Advantage NLM Management Utility options and then select "Configuration Parameters Affecting
Memory". Sample load settings affecting memory are shown below.

This screen displays the current parameter settings as well as the amount of file server memory being
used to support these configurable settings. The memory usage (displayed in bytes) shows the totals for

Advantage Management Information 87

Advantage Database Server Guide

each setting. To determine how much memory is required per incremental setting, divide the memory size
by the number configured.

Note The total memory used by the Advantage NLM on the file server is more than what is shown. There
is additional memory used that is not configurable, such as the module size of ADS.NLM, and the
memory used by other Advantage Database Server threads.

The NetWare MONITOR.NLM can be used to determine how much memory is actually being used by the
Advantage NLM. To determine the module size of ADS.NLM, select "System Module Information" and
then "Advantage Database Server." The "Module Size" should be displayed. To determine the amount of
memory allocated by the Advantage Database Server, select "Large memory allocations", "Medium
memory allocations", and "Small memory allocations". Sum those three memory allocation values.
Subtract the amount of file server memory being used to support the configurable settings (displayed in
the Advantage NLM Management Utility) from the sum of the three memory allocation values to
determine the total amount of non- configurable file server memory used by Advantage.

Configuration Parameters Not Affecting Memory: To view the currently loaded parameters that do not
affect memory when the Advantage Database Server is loaded, but instead affect other Advantage
settings, select "Configuration Parameters" from the Advantage NLM Management Utility options and
then select "Configuration Parameters Not Affecting Memory". The default load settings that do not affect
memory when the Advantage Database Server is loaded are shown below.

This screen displays the current parameters, such as error and assert log paths, that are defined at load
time but have no direct effect on file server memory usage.

Connected Users
Selecting "Connected Users" from the Advantage NLM Management Utility screen displays a list of all
connected users by their NetWare login names. Preceding the user name is the NetWare connection
number for that user. This is the same NetWare connection number you will see in MONITOR.NLM.

"Connected Users" are the users to which the Advantage Database Server will service client requests. If a
user is having problems communicating with the Advantage Database Server, verify that the user is
connected. You can view which files the user has open by selecting the user (press Enter). Once the list
of files is displayed, the locks on that file can be displayed by pressing Enter while the file name is
highlighted. The Advantage Locking Mode used with the file will also be displayed along with the file
name.

Open Files
"Open Files" displays the currently opened tables or index files. Preceding the file name is the Advantage
Locking Mode by which the file was opened. The Advantage Proprietary Locking is denoted with "ADS",
and Advantage Compatibility Locking is denoted with "CDX" for IDX/CDX file compatibility locking or
"NTX" for NTX file compatibility locking. It also indicates which users currently have the files open.

By selecting either "Open Data Files" or "Open Index Files", a list of the files will appear on the screen. To
find out who has the files open, select the file (by pressing Enter) and the connected user will display.

Worker Thread Information

Advantage Database Server Worker Threads perform the actual database operations on the server.
"Worker Thread Information" displays the current number of Worker Threads being used, the maximum
number of Worker Threads used at any one time, and the configured number of Worker Threads. If the

88 Advantage Management Information

 Advantage Database Server Guide

Max Used value is equal to the Configured value, you may want to increase the "Number of Worker
Threads" setting (See Advantage Database Server Configuration) to increase overall Advantage
Database Server throughput.

Advantage Configuration Utility for Windows NT/2000

The Advantage Database Server Service must be started in order to use the Configuration Utility. If the
Configuration Utility has been started while the Advantage Database Server Service is stopped or not
started, the message, "ADS Service not started" will display next to Service Up Time. In addition, all
information in the Database Info window and the Installation Info window will appear blank. The
Configuration Utility tab and all configuration sub-tabs, however, will be functional.

If the Advantage Database Server Service has been started after the Configuration Utility has been
started, click the Connect button. Database and Installation information will be displayed for the newly
started Advantage Database Server Service.

The Advantage Configuration Utility is divided into three sections:

• Database Information
• Installation Information
• Configuration Utility

Database Information
The Database Info tab includes rows for the following database items:
• Users
• Connections
• Work Areas
• Tables
• Index Files
• Data Locks
• Worker Threads

Status columns provide more information about each of these database items. Definitions of the four
columns are listed below.

Current: The current number of an item in use.

Max Used: The maximum number of the item actually in use at one time since the Advantage Database
Server Service was started.

Note "Max Used" information is provided to help system administrators fine-tune the configuration of the
Advantage Database Server Service for optimal performance. For example, if after several days of active
use, the maximum number of data locks in use at one time is 50, the system administrator could
reconfigure the Advantage Database Server Service to allocate 55 data locks.

Configured: Shows the maximum number of an item that the Advantage Database Server Service has
available.

Rejected: Indicates that a configured value has been exceeded. If numbers frequently appear in this
column, it indicates that the Advantage Database Server Service should be started with increased
configuration parameters or a larger user option should be purchased.

Advantage Management Information 89

Advantage Database Server Guide

Installation Information
The following information appears in the Installation Information window. To access this window, select
the Installation Info tab. This information is entered/calculated when the Advantage Database Server is
installed.

Registered To: The name of the company that owns the product.

Serial Number: The unique serial number of your copy of the Advantage Database Server.

User Option: The maximum number of users (client workstations) that can be connected to this version
of the Advantage Database Server.

ADS Revision: The revision number of the Advantage Database Server.

OEM Character Set: The OEM/localized character set used with Advantage client applications in
International versions of the Advantage Database Server.

ANSI Character Set: The ANSI character set that determines the ANSI collation order used with
Advantage Windows clients.

Install Date: The date the Advantage Database Server was installed.

Eval Expiration Date: Displayed for evaluation units only. The date the Advantage Database Server
evaluation period will expire.

Log Entries: The number of errors or warnings that have been logged to the Advantage error log file
(ADS_ERR.DBF) since the Advantage Database Server Service was started.

Advantage Database Server for Windows 95/98/ME GUI

Once the Advantage Database Server for Windows 95/98/ME has been started, the GUI will be available
with Database and Installation information displayed for the newly started Advantage Database Server.
The Configuration Utility will also be available.

The Advantage Database Server for Windows 95/98/ME GUI is divided into three sections:

Database Information
Installation Information
Configuration Utility

Advantage Management Utility

for NetWare, Windows NT/2000, and Windows 95/98/ME
The Advantage Management Utility is a 32-bit end-user database management utility that provides
access to Advantage Database Server management information for NetWare, Windows NT/2000, and
Windows 95/98/ME network operating systems. Using this utility, networked client PCs can access
management information on servers running the Advantage Database Server. The Advantage
Management Utility brings the convenience of watching Advantage Database Server activity information
to your client machine. This aids in development, troubleshooting, and performance monitoring which, in
turn, increases productivity.

90 Advantage Management Information

 Advantage Database Server Guide

The Advantage Management Utility has been incorporated into the Advantage Data Architect. However, a
stand-alone version is also available from the Downloads/Tools & Utilities section of the Advantage
Developer Zone Web site at: http://solutions.AdvantageDatabase.com.

Through a persistent connection to the Advantage Database Server, the Advantage Management Utility
allows you to:
• Browse general database activity information
• Check installation information
• View connected users
• View open files
• Check configuration parameters that do and do not affect server memory
• View communication statistics

Database Information
The Database Information screen includes rows for some of the main database items: Users,
Connections, Work Areas, Tables, Index Files, Data Locks, and Worker Threads.

Installation Information
The Installation Information screen includes information that is entered/calculated when the Advantage
Database Server is installed.

Connected Users
The Connected Users screen displays a list of all connected users. The User Information displayed
includes the user's computer name, the NetWare connection number (if applicable), the user's data
dictionary user name (if applicable), and the user's network address.

Open Files
The Open Files screen displays the currently open data files or index files. Preceding the file name is the
locking method used to open the file with Advantage.

Configuration Parameters Affecting Memory

The Configuration Parameters Affecting Memory screen shows the currently loaded parameters affecting
memory when the Advantage Database Server is loaded.

Configuration Parameters Not Affecting Memory

The Configuration Parameters Not Affecting Memory screen displays the current parameters that are
defined at load time but have no direct effect on file server memory usage.

Communication Statistics
The Communication Statistics screen shows the packet and low level network status.

Advantage Management Information 91

Advantage Database Server Guide

Advantage Management API

for NetWare, Windows NT/2000, and Windows 95/98/ME
The Advantage Database Server can supply management information directly to Advantage client
applications via the Advantage Management API. The Advantage Management Utility described above is
a Delphi application written to call the Advantage Management API. The following information can be
obtained via the Advantage Management API:

• Database activity information

• Installation information
• Information about connected users
• Information about tables and index files that are open
• Configuration parameters that do and do not affect server memory
• Communication statistics
• Worker thread activity information
• Owner of a file or record lock
• List of locks on a given table
• Advantage server type

In addition to the ability to retrieve the above information, Advantage applications have the ability to
disconnect a user from the Advantage Database Server.

Refer to your Advantage client-specific documentation for more information about specific Management
APIs.

92 Advantage Management Information

Advantage Database Server Guide

Performance Factors

General Performance Factors

The following are general keys to performance when using Advantage.

Increase Memory and CPU Speed on the Server

With the Advantage Database Server, the file server is no longer an unintelligent shared hard drive. The
server CPU and memory are now more fully utilized. So, increasing the amount of memory and the speed
of the CPU should always help performance of the Advantage Database Server. Servers with only 8 MB
of RAM will probably not provide optimum performance. If the workstations are Pentium II's, and the
server is a 486, Advantage may not provide the best performance. The file server should have at least as
much RAM and as fast a CPU as the client workstations.

Open All Tables At Startup

The Advantage Database Server opens all files from the server. When a file open request is generated
from an Advantage client, extra checks and additional operations are performed (such as converting drive
letters into server and volume/share names) that do not occur when using a non-Advantage driver. Thus,
Advantage is usually slower than non-client/server drivers when opening files. In general, for best
performance, all tables and index files should be opened at application startup and should be kept open
during the entire application. If tables must be opened throughout the application, using UNC paths and
using "ignore rights" security may slightly increase the speed of opens.

Use Advantage Optimized Filters

Convert your applications to use Advantage Optimized Filters (AOFs) rather than traditional record filters.
AOFs can be up to 1000 times faster than traditional record filters. See Advantage Optimized Filter for
more information.

Optimize Use of Advantage Read-Ahead Record Caching

Proper use of Read-Ahead Record Caching in your applications can improve Skip operation performance
by 100 times. See Read-Ahead Record Caching for more information.

Turn Foreground Performance Boost Off

If using the Advantage Database Server for Windows NT/2000, turn off the "foreground boost for the
foreground process" on the Windows NT/2000 Server. Since the Advantage Database Server is a
service, it runs as a background process. If foreground processes are given a performance boost,
Advantage Database Server performance will suffer. Foreground boost can be turned off via the
Performance tab under the System Properties icon in the Control Panel folder.

Do Not Use NTX Indexes and DBT Memos

There are several non-performance reasons to use index and memo formats other than NTX indexes.
NTX index files allow only one index order per index file. Both CDX and ADI indexes are compound
indexes. That means you can have multiple individual index orders per CDX or ADI index file. Having
compound index files makes application development easier because there are fewer files to open and
maintain. CDX and ADI indexes also have the concept of auto-open index files. If a CDX or ADI index file
has the same base name as the table name, that index file will be automatically opened when the table is
opened and cannot be closed until it is automatically closed when the table is closed. This makes
application development even easier with CDX and ADI indexes than with NTX indexes, because your
application never needs to open or close index files. NTX indexes have no auto-open functionality.

93 Performance Factors
Advantage Database Server Guide

More important than the "ease of development" features with NTXs vs. CDXs or ADIs, is the poor
performance associated with NTX indexes and DBT memo files relative to the other index and memo file
formats. CDX and ADI indexes store index data in a compressed format. NTX indexes do not. For
example, if you have an index created on "last name", and there are 69 "Smith" last names in the index,
an NTX will literally have "Smith" 69 times in the index, including trailing spaces. CDX and ADI indexes,
on the other hand, would store "Smith" a maximum of one time, and never literally store trailing spaces.
This means CDX and ADI indexes can store much more data in a smaller file. Any time the index is
accessed to be read, searched, or updated, there is much less data that needs to be read from disk with
CDX and ADI indexes than with an NTX index. Since file I/O is so slow relative to any operation you can
do in memory, NTX index access will always be much slower than CDX or ADI index access because 2 to
10 times the amount of disk reads and writes will occur.

DBT memo files also perform much more poorly than FPT or ADM memo files. This is mainly due to the
extra disk space needed for DBT memos due to their large and inefficient block size. But more
importantly, is that DBT memos do not store the memo data length anywhere, whereas FPT memos and
ADM memos do have the length of memo data readily accessible. This means that any time memo data
is read from a DBT memo, the length of the DBT memo data must be sequentially counted, byte by byte,
until a special terminator indicator is reached. FPT and ADM memos have the memo length available so
that no sequential search is ever required. The sequential counting of memo data length causes DBT
memo access to be slower than FPT and ADM memo access.

Limit the Number of Index Orders (Tags) Per CDX

In a multi-user system where data is being updated, developers have a decision to make regarding the
trade-off between ease of development and performance when using CDX index files. As discussed in
the "Do Not Use NTX Indexes and DBT Memos" section above, CDX indexes can make application index
usage very simple because all index orders (tags) can be contained within a single auto-open compound
CDX index file which relieves the application from having to explicitly open or close index files. CDX index
files, however, do not have per-index order write lock functionality. There is only per-file write locking
available. This means that any time any application in the multi-user system is updating an individual
index order in the CDX, no other application on the entire system can gain access to any index order in
the CDX index file for reading or writing. When there are many index orders per CDX and updates are
occurring in a multi-user system, that CDX will become a bottleneck and lead to poor application
throughput.

If, on the other hand, index orders are divided among multiple CDX index files, updating a single index
order in one of the CDX index files will have no effect on access to the other CDX index files. For
example, if you have 50 index orders in a single CDX index file, and some application needs to write to
the "last name" index order in that CDX, no other users on the system will be able to access any index
orders in that CDX while the update is occurring. If, however, you created 5 separate CDX index files,
each with 10 index orders, some application updating the "last name" index order would only keep other
users on the system from accessing one of the CDX index files while that update was in progress. The
other 4 index files would be available to be read from, or written to, by all other applications on the
network.

In this example scenario, the ease of development vs. performance trade-off can be seen. For maximum
ease of development, putting all 50 index orders in a single auto-open CDX index file would require no
specific index open/close code to be written. For best performance, however, dividing up the index orders
into 5 CDX index files and writing the extra code to make sure all index files are opened and closed,
would provide optimum multi-user performance. Note that this issue only applies to CDX index files and
not ADI index files because ADI index files do have per-index order write locking functionality.

94 Performance Factors
 Advantage Database Server Guide

Performance Factors Relative to Non-Client/Server

The following are keys to performance when comparing Advantage to non-client/server solutions.

Multiple Users Usually Required

Multiple users are almost always required to see performance gains with Advantage versus non-
client/server solutions. Exceptions are index creation, copy to, append from, pack, and zap (also referred
to as empty table) operations, in which case Advantage will always be faster. The use of the Advantage
Database Server processing may slow single users, but should greatly increase multi-user performance.

Open Tables for Shared Use

Open tables for "shared" use. First, if tables are opened for "exclusive" use, multi-user access is
eliminated. Also, when non-client/server drivers open files exclusively (or if files are open shared by a
single user and you are using a Windows 95/98/ME client, or a Windows NT/2000 client against a
Windows NT/2000 Server), they can cache information on the client which will make non-client/server
drivers appear faster. Exceptions to this are index creation, copy to, append from, pack, and zap (also
referred to as empty table), where exclusive use of the table is either required or usually makes sense. If
tables are opened for "exclusive" use, Advantage may not increase read and write performance versus
non-client/server drivers.

The More Indexes/Tags Open, the Better

The more indexes/tags that are open, the better Advantage performance will be relative to non-
Advantage drivers. In most multi-user systems, there is a lot of contention for index access. Every index
access, whether it be for a read, skip, seek, write, etc., requires an internal index lock to be obtained. The
initial attempts to lock the index files will often fail because another user already has the index locked.
Non-client/server drivers try and retry the index locks from the client, which leads to increased network
traffic and very slow performance. Advantage performs index locking on the server using an intelligent
read-through locking queuing system, which greatly increases performance. If applications generally use
very few or no indexes/tags, then the Advantage Database Server may not greatly increase read and
write performance versus non-client/server drivers.

Note The above does not recommend that you create and open more indexes/tags to improve
performance. In fact, applications with few indexes/tags usually perform better than similar applications
with more indexes/tags. The point is, that if your existing application already uses many indexes/tags,
Advantage should significantly improve performance compared to non-client/server drivers.

The Larger the Tables, the Better

The larger the tables and index files, the better Advantage will perform in comparison to non-client/server
drivers. If tables and index files are small, non-client/server drivers do not have much data to read and
write to and from the server. The most significant way Advantage increases performance is by reducing
network traffic. If the non-client/server driver does not generate much network traffic because data files
are small, the benefit of using Advantage is eliminated. If tables are generally small, that is, they have
fewer than 10,000 records, Advantage may not greatly increase read and write performance versus non-
client/server drivers.

Note The above does not recommended that you increase the size of your tables and indexes to
improve performance. In fact, applications with smaller tables and indexes usually perform better than
similar applications with larger tables and indexes. The point is, that if your existing application already
uses large tables and indexes, Advantage should significantly improve performance compared to non-
client/server drivers.

Performance Factors 95
Advantage Database Server Guide

Read the Data in Performance Tests

If writing a performance test that does skip and seek operations, be sure to read the data to which you
are skipping or seeking. Non-client/server drivers do not necessarily automatically read over the
corresponding table record after a skip or a seek. The Advantage Database Server "bundles" the record
with the skip or seek result back to the client. 99% of the time, applications read the data to which they
are skipping or seeking. So make sure your performance test does, too.

Speed of the Network

The network infrastructure itself plays a key role in database application performance. Non-client/server
database applications transport all data from the server to the workstation and vice versa. Even with the
Advantage Database Server client/server architecture, which significantly reduces network traffic,
database applications generate more traffic than other types of applications. Thus, the speed of your
network and the number of bridges and routers between the workstation and the server, play a role in
performance. In general, the slower the communications between the workstation and server, the faster
Advantage applications will perform relative to non-client/server applications. This is simply the result of
client/server processing reducing the amount of data transferred across the network. Applications using
the Advantage Database Server in a WAN environment will produce very impressive performance
improvements.

96 Performance Factors
Advantage Database Server Guide

Troubleshooting and Technical Support

Technical Support (U.S. and Canada)

Extended Systems offers 30 days of free Web Site technical support for all Advantage products. After
that, you can purchase an annual service contract for web site technical support that will cover any
questions regarding an Advantage product. Other service options are available if you need telephone
support with an Advantage product. Contact Advantage Sales at 800-235-7576 x5030 for more
information.

Annual Service Contract

Our Web Assist annual service contract provides you ….

Web Assist • Unlimited web site access to FAQs and knowledge base on
Advantage products. Available 24 hours a day, seven days
a week
$95 per year for
• Requests for technical information posted for assistance
each site with Advantage products. Available Monday through Friday,
8-5 Mountain Time

Advantage Solutions
Try our Advantage Solutions web site for quick and easy access to the information you need. You can
find product information, code samples and technical support notes to assist you.

Web Support http://Solutions.AdvantageDatabase.com Unlimited web site access to FAQs

and knowledge base access available
Free 24 hours a day, seven days a week.

Web Assist http://Solutions.AdvantageDatabase.com Requests for technical information

posted for assistance with Advantage
$95 per year for products. Available Monday through
each site Friday, 8 - 5 Mountain Time
Internet/FTP http://Solutions.AdvantageDatabase.com Support files available for download
from our FTP site 24 hours a day,
Free seven days a week.

How to Sign Up
To purchase your Personal Identification Number (PIN) for Advantage Web Assist, go to
www.AdvantageDatabase.com/go/webassist.

97 Troubleshooting and Technical Support

Advantage Database Server Guide

www.AdvantageDatabase.com
Up to date technical and troubleshooting information about the Advantage Database Server can be found
on the Advantage Web site at www.AdvantageDatabase.com. Our Service/Support Web pages are
dedicated to providing technical solutions to Advantage customers. Access to this Web site is free of
charge for all Advantage product owners. After registering for a PIN, all resources will be available to you
including the Advantage Knowledge Base, Advantage FAQs, and the Advantage Developer's News
Group.

Troubleshooting in the NetWare Environment

Error Logs
The Advantage Database Server provides error and warning information in two files: ADS_ERR.DBF and
ASSERT.LOG. Errors and warnings are logged when a recoverable, invalid condition occurs on the
Advantage Database Server. For specific error explanations, see the Advantage Error Guide Windows
Help File (ADSERROR.HLP).

ADS_ERR.DBF is a DBF table to which any application or data error or warning is recorded. Errors and
warnings written to this error log file are not necessarily critical errors but are key to tracing potential
problems in the system or client applications. This error log may be configured to a maximum file size to
prevent excessive disk space usage. See Advantage Database Server Configuration, to change this
setting.

ASSERT.LOG is a file to which critical Advantage internal assertion failures are recorded. Assertions are
internal "sanity checks" placed throughout the Advantage Database Server code to verify that code paths
and data are valid during operation. If an assertion failure occurs on your file server, the Advantage NLM
will be halted and a message will appear on the file server monitor. An error will also be recorded to the
Advantage error log file. For more information on NLM Assertions, see the section below.

These log files are configurable to be placed in a specified network directory location. See Advantage
Database Server Configuration for more information.

Assertions
An important functional requirement of the Advantage Database Server is to not cause a server AbEnd
(Abnormal End). During development of the Advantage Database Server, every effort was made to detect
possible causes of NetWare server AbEnds and to properly recover in those situations.

As an additional safeguard, the Advantage Database Server contains assertion checks. An assertion
check is a run-time verification of the current state of the Advantage Database Server. Assertion checks
are used to verify function parameters, memory contents, etc. Assertion checks will halt Advantage
Database Server processing when an unknown state is encountered, rather than allowing the Advantage
Database Server to continue processing and possibly cause a server AbEnd.

A failed assertion check causes the currently active Advantage Database Server thread to enter an
infinite loop that displays a warning message on the main console screen of the file server. A message is
also displayed on the Advantage NLM screen. An entry is made in the Advantage Assertion Failure Log
(ASSERT.LOG) and a current Advantage Database Server internal data dump is written to a temporary
file (_T- #####.TMP where ##### is a five digit number). By default, the Assertion Failure log file and
temporary file are located in the root directory of the SYS volume on the file server where the Advantage
Database Server is loaded. The Assertion Failure log file can be configured to be located on any valid file
server directory.

98 Troubleshooting and Technical Support

 Advantage Database Server Guide

Important! If an assertion failure occurs, all users must exit their Advantage applications.

Unloading the Advantage NLM in an assertion failure state does not generally cause problems. However,
an assertion failure creates an unknown state, so the possibility exists that your file server may go down.
To minimize possible damage:

1. Have all users connected to the file server (Advantage or otherwise) exit their applications.
2. Wait a few minutes for the file server to flush all dirty cache buffers.
3. Unload the Advantage NLM. If the Advantage NLM unloads successfully, you can resume normal
activity.
4. Save the following files: The Advantage Assertion Failure Log file (ASSERT.LOG), the temporary file
containing the Advantage Database Server internal data dump (_T-#####.TMP, where ##### is a five
digit number), and the Advantage Error Log file (ADS_ERR.DBF).

After you save the necessary files, re-load the Advantage NLM on the network file server and resume
your Advantage applications. Then, contact Advantage Technical Support.

Troubleshooting in the Windows NT/2000 Environment

Note The Advantage Database Server for Windows NT/2000 is a Windows NT/2000 Service. It cannot
run as a standard Windows application. If running the Advantage Database Server Service is attempted
from Windows 95 or Windows 98, the following error will occur: "The ADS.EXE file is linked to missing
export NETAPI32.DLL NetShareGet Info". Refer to Installing and Starting the Advantage Database
Server for Windows NT/2000 for more information on Windows NT/2000 Services and how to start them.

Event Log
Windows NT/2000 event logging provides a centralized way for applications and services to record
events such as when a service was stopped or started as well as error conditions. The Windows NT/2000
Event Viewer provides a standard user interface for viewing logged events. There are three types of
event logs:

• System Log - tracks Windows NT/2000 system information

• Security Log - tracks events triggered by security violations
• Application Log - tracks events written by an application

The Event Viewer is accessed through the Administrative Tools group/folder. Select the type of log file
you want to view (System, Security, or Application). Double click the event in the list to view the Event
Detail Window.

Information, warnings, and errors pertaining to the Advantage Database Server Service is recorded in the
Event Viewer Application Log. Information messages are used to record when the Advantage Database
Server Service was started or stopped. Advantage Database Server Service warnings alert users of
recoverable problems. Errors, however, are used to display non-recoverable conditions that are likely to
cause an application failure.

Error Log
For troubleshooting purposes, the Advantage Database Server Service maintains an error log.

Troubleshooting and Technical Support 99

Advantage Database Server Guide

As a default, the error log, ADS_ERR.DBF, is located in the root of the C: drive. This error log file may be
configured to be located on any valid server directory. When an error occurs, pertinent error information is
appended to this file.

Errors are logged when a recoverable, invalid condition occurs in the Advantage Database Server
Service. All errors are returned to the client. For specific error explanations, see the online Error Help file,
ADSERROR.HLP.

Assertions
A primary functional requirement of the Advantage Database Server Service is to not cause an exception
or server crash. During development of the Advantage Database Server Service, every effort was made
to detect possible causes of exceptions and to properly recover in those situations.

As an additional safeguard, the Advantage Database Server Service contains assertion checks. An
assertion check is a run-time verification of the current state of the Advantage Database Server Service.
Assertion checks are used to verify function parameters, memory contents, etc. Assertion checks will halt
Advantage Database Server Service processing when an unknown state is encountered, rather than
allow the Advantage Database Server Service to continue processing and possibly cause an exception.

A failed assertion check causes the currently active Advantage Database Server Service thread to enter
an infinite loop that displays a warning message on the main console screen of the server. A message
box is also displayed on the server screen. An entry is made in the Advantage Assert Log
(ASSERT.LOG) and a current Advantage Database Server Service memory dump is written to a
temporary file (_T- ####.TMP where #### is a one to four digit hexadecimal number). By default, the
ASSERT log file and temporary file are located at the root of the C: drive.

The ASSERT log file can be configured to be located on any valid server directory.

Important! If an assertion failure occurs, all users must exit their Advantage applications.

Stopping an Advantage Database Server Service in an assertion failure state does not generally cause
problems. However, an assertion failure creates an unknown state, so the possibility exists that an
exception may occur. To minimize possible damage:

1. Have all users connected to the Advantage Database Server exit their applications.
2. Wait a few minutes for the server to flush all buffers.
3. Stop the Advantage Database Server Service. Once the Advantage Database Server Service is
stopped, you can resume normal activity.
4. Save the following files:
• Advantage Assert Log file (ASSERT.LOG)
• The temporary file containing the Advantage Database Server Service memory dump (_T-
####.TMP, where #### is a one to four digit hexadecimal number)
• Advantage Database Server Error Log file (ADS_ERR.DBF)
5. After you save the necessary files, re-start the Advantage Database Server Service and resume your
Advantage applications. Then, contact Advantage Technical Support.

100 Troubleshooting and Technical Support

 Advantage Database Server Guide

Troubleshooting in the Windows 95/98/ME Environment

Error Log
For troubleshooting purposes, the Advantage Database Server maintains an error log.

As a default, the error log, ADS_ERR.DBF, is located in the root of the C: drive. This error log file may be
configured to be located on any valid server directory. When an error occurs, pertinent error information is
appended to this file.

Errors are logged when a recoverable, invalid condition occurs in the Advantage Database Server. All
errors are returned to the client. For specific error explanations, see the online Error Help file,
ADSERROR.HLP.

Assertions
A primary functional requirement of the Advantage Database Server is to not cause an exception or
server crash. During development of the Advantage Database Server, every effort was made to detect
possible causes of exceptions and to properly recover in those situations.

As an additional safeguard, the Advantage Database Server contains assertion checks. An assertion
check is a run-time verification of the current state of the Advantage Database Server. Assertion checks
are used to verify function parameters, memory contents, etc. Assertion checks will halt Advantage
Database Server processing when an unknown state is encountered, rather than allow the Advantage
Database Server to continue processing and possibly cause an exception.

A failed assertion check causes the currently active Advantage Database Server thread to enter an
infinite loop that displays a warning message on the main console screen of the server. A message box is
also displayed on the server screen. An entry is made in the Advantage Database Server Assert Log
(ASSERT.LOG) and a current Advantage Database Server memory dump is written to a temporary file
(_T####.TMP where #### is a one to four digit hexadecimal number). By default, the ASSERT log file
and temporary file are located at the root of the C: drive.

The ASSERT log file can be configured to be located on any valid server directory.

Important! If an assertion failure occurs, all users must exit their Advantage applications.

Stopping the Advantage Database Server executable in an assertion failure state does not generally
cause problems. However, an assertion failure creates an unknown state, so the possibility exists that an
exception may occur. To minimize possible damage:

1. Have all users connected to the Advantage Database Server exit their applications.
2. Wait a few minutes for the server to flush all buffers.
3. Shut down the Advantage Database Server executable. Once the Advantage Database Server is
stopped, you can resume normal activity.
4. Save the following files:
• Advantage Assert Log file (ASSERT.LOG)
• The temporary file containing the Advantage Database Server memory dump (_T-####.TMP,
where #### is a one to four digit hexadecimal number)
• Advantage Database Server Error Log file (ADS_ERR.DBF)
5. After you save the necessary files, re-start the Advantage Database Server executable and resume
your Advantage applications. Then, contact Advantage Technical Support.

Troubleshooting and Technical Support 101

Advantage Database Server Guide

Avoiding OEM Collation Mismatch Errors

A single Advantage application can connect to multiple Advantage Database Servers, or one or more
Advantage Database Servers and the Advantage Local Server. If such an application is using ANSI or
OEM collation with non-USA collation sets, care must be taken to avoid a 5092 Collation Mismatch error.
To avoid such an error, make sure the same OEM collation language is selected when installing the
Advantage Database Server and the Advantage clients. The OEM collation language selected during an
Advantage client install will be placed in the Advantage Local Server configuration file, ADSLOCAL.CFG.
Note that when installing the U.S. version of the Advantage Database Server, USA is the only OEM
collation language available, so there is no ability to select a different OEM collation language.

Note If one of the following conditions is present, no Collation Mismatch errors will occur:
• Your application is connecting to a single Advantage Database Server
• Your application is connecting to just the Advantage Local Server
• USA OEM collation language is always being used

Note If you change your OEM collation language from one language to another, you need to rebuild all of
your index files.

Avoiding ANSI Collation Mismatch Errors

A single Advantage application can connect to multiple Advantage Database Servers, or one or more
Advantage Database Servers and the Advantage Local Server. If such an application is using ANSI or
OEM collation with non-USA collation sets, care must be taken to avoid a 5092 Collation Mismatch error.
To avoid such an error, make sure the same ANSI collation language is being used with all connections.
To ensure the ANSI collation languages are the same, verify one of the following is true:

1) This first option is the simpler method to make sure the ANSI collation languages are the same for all
connections. Specifically select an ANSI collation language when installing the Advantage Database
Server and Advantage clients. Make sure to specify the same ANSI language for all installs. The
ANSI collation language selected during an Advantage client install will be placed in the Advantage
Local Server configuration file, ADSLOCAL.CFG. If the ANSI language you desire is not shown in the
list, the ANSICHR.EXE utility can be used to add an ANSI language to the file containing the
available ANSI languages.

2) If you do not wish to use option 1 above, select <DEFAULT ON MACHINE> for the ANSI collation
language when installing the Advantage Database Server and the Advantage clients. All computers
used for installation of the Advantage Database Server should be running the same Windows
operating system. The computer running an application that connects to the Advantage Local Server
should also be running this same OS. In addition to the operating systems being the same, all
computers should be using the same ANSI collation language (which is specified via the Regional
Settings icon).

Note If one of the following conditions is present, no Collation Mismatch errors will occur:
• Your application is connecting to a single Advantage Database Server
• Your application is connecting to just the Advantage Local Server
• English ANSI collation language is always being used

Note If you change your ANSI collation language from one language to another, you need to rebuild all of
your index files.

102 Troubleshooting and Technical Support